MCP Financial Datasets Server

MCP server providing financial data from financialdatasets.ai with backtesting support.

Overview

This server provides comprehensive financial data including company financials, stock prices, crypto prices, and company news from the financialdatasets.ai API. All tools are backtesting-compliant, ensuring no future information leakage.

Features

• Backtesting Compliant: All data strictly filtered to before cutoff date

• Company Financials: Income statements, balance sheets, cash flow statements

• Historical Prices: Stock and cryptocurrency price data (OHLCV)

• Company News: News articles with sentiment analysis

• Flexible Periods: Annual, quarterly, or trailing twelve months (TTM) data

• Crypto Support: 100+ cryptocurrencies with historical price data

Tools

Financial Statements

get_income_statements

Get historical income statements for a company.

Parameters:

• ticker (str): Stock ticker symbol (e.g., AAPL, MSFT, GOOGL)

• cutoff_date (str): Only return data with report_period <= cutoff_date

• period (str): "annual", "quarterly", or "ttm" (default: "annual")

• limit (int): Number of historical periods (default: 4)

Returns: JSON array with revenue, net_income, operating_income, earnings_per_share, etc.

get_balance_sheets

Get historical balance sheets for a company.

Parameters: Same as get_income_statements

Returns: JSON array with total_assets, cash_and_equivalents, total_debt, shareholders_equity, etc.

get_cash_flow_statements

Get historical cash flow statements for a company.

Parameters: Same as get_income_statements

Returns: JSON array with net_cash_flow_from_operations, capital_expenditure, free_cash_flow, etc.

Stock Prices

get_historical_stock_prices

Get historical stock price data (OHLCV) for a date range.

Parameters:

• ticker (str): Stock ticker symbol (e.g., AAPL, TSLA, NVDA)

• start_date (str): Start date in YYYY-MM-DD format

• end_date (str): End date in YYYY-MM-DD format (clamped to cutoff_date)

• cutoff_date (str): Maximum date for returned data

• interval (str): "minute", "hour", "day", "week", or "month" (default: "day")

• interval_multiplier (int): Multiply interval (e.g., 5 with "minute" = 5-minute bars)

Returns: JSON array with open, close, high, low, volume, timestamp fields

Company News

get_company_news

Get recent news articles about a company with sentiment analysis.

Parameters:

• ticker (str): Stock ticker symbol

• cutoff_date (str): Only return news published before this date

Returns: JSON array (up to 20 articles) with title, url, date, author, source, sentiment

Cryptocurrency

get_available_crypto_tickers

Get list of all available cryptocurrency tickers.

Returns: JSON array of ticker symbols (e.g., ["BTC-USD", "ETH-USD", "SOL-USD"])

get_crypto_prices

Get historical cryptocurrency price data (OHLCV).

Parameters:

• ticker (str): Crypto ticker symbol (e.g., BTC-USD, ETH-USD, SOL-USD)

• start_date (str): Start date in YYYY-MM-DD format

• end_date (str): End date in YYYY-MM-DD format (clamped to cutoff_date)

• cutoff_date (str): Maximum date for returned data

• interval (str): "minute", "hour", "day", "week", or "month" (default: "day")

• interval_multiplier (int): Multiply interval

Returns: JSON array with open, close, high, low, volume, timestamp fields

Environment Variables

Required:

• FINANCIAL_DATASETS_API_KEY: API key for financialdatasets.ai

Get your API key at: https://financialdatasets.ai/

Installation

Usage

Testing Locally

As Git Submodule

Backtesting Compliance

This server implements strict backtesting controls:

Financial Statements

• Filter Parameter: report_period_lte={cutoff_date} in API requests

• Guarantee: Only returns financial statements for periods ending on or before cutoff_date

• Note: Report period is when the fiscal period ended, not when filed with SEC

Price Data

• End Date Clamping: If end_date > cutoff_date, automatically clamps to cutoff_date

• Guarantee: No price data returned after cutoff_date

• Safe Pattern: Always request with end_date at or before cutoff_date

Company News

• Filter Parameter: end_date={cutoff_date} in API requests

• Guarantee: Only returns news published before cutoff_date

• Includes: Title, URL, publication date, author, source, sentiment

Disabled Tools

The following tools are intentionally disabled for backtesting compliance:

• get_current_stock_price - Always returns latest price (future information)

• get_current_crypto_price - Always returns latest price (future information)

• get_sec_filings - API only provides report_date, not filing_date (when made public)

Alternative: Use get_historical_stock_prices or get_crypto_prices with start_date=end_date=cutoff_date to get price at a specific historical date.

API Details

Base URL: https://api.financialdatasets.ai

Authentication: X-API-KEY header (optional but recommended for higher rate limits)

Endpoints Used:

• /financials/income-statements/

• /financials/balance-sheets/

• /financials/cash-flow-statements/

• /prices/ (stock prices)

• /news/ (company news)

• /crypto/prices/ (cryptocurrency prices)

• /crypto/prices/tickers (available crypto tickers)

Error Handling

All tools return user-friendly error messages:

• Missing or invalid API key

• Invalid ticker symbols

• Date parsing errors

• API request failures

• No data found for requested parameters

Errors are returned as strings rather than raising exceptions.

Example Queries

Get Apple's Annual Financials

Get Bitcoin Price History

Get Tesla News

Limitations

• SEC Filings: Not available due to lack of filing_date field in API

• Real-time Data: Current price endpoints disabled for backtesting compliance

• Rate Limits: Subject to financialdatasets.ai API rate limits

• API Coverage: Data availability depends on what financialdatasets.ai provides

Dependencies

• fastmcp: MCP server framework

• httpx: Async HTTP client for API requests

• python-dotenv: Environment variable management