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

cd mcp-financial-datasets
uv sync

Usage

Testing Locally

mcp run -t sse financial_datasets_server.py:mcp

As Git Submodule

git submodule add <repo-url> mcp-servers/mcp-financial-datasets

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

income = await get_income_statements(
    ticker="AAPL",
    period="annual",
    limit=4,
    cutoff_date="2024-01-01"
)

Get Bitcoin Price History

prices = await get_crypto_prices(
    ticker="BTC-USD",
    start_date="2024-01-01",
    end_date="2024-06-01",
    interval="day",
    cutoff_date="2024-06-01"
)

Get Tesla News

news = await get_company_news(
    ticker="TSLA",
    cutoff_date="2024-06-01"
)

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

Testing

Setup

1. Install test dependencies:

uv pip install -e ".[test]"

2. Configure environment variables by copying .env.example to .env:

cp .env.example .env

3. Add your API key to .env:
   • FINANCIAL_DATASETS_API_KEY - Required from https://financialdatasets.ai/

Running Tests

Run all tests:

pytest

Run with verbose output:

pytest -v

Run specific test file:

pytest tests/test_financial_datasets_server.py

Run specific test:

pytest tests/test_financial_datasets_server.py::test_get_income_statements -v

Test Coverage

The test suite covers:

• Financial statements: Income statements, balance sheets, cash flow statements (annual, quarterly, TTM)
• Stock prices: Historical price data with different intervals and cutoff date enforcement
• Company news: News article retrieval with date filtering
• Cryptocurrency: Available tickers, price data for multiple crypto pairs
• Error handling: Invalid tickers, date validation, API errors
• Edge cases: Large limits, different periods, interval multipliers

Note: Tests make real API calls and require a valid FINANCIAL_DATASETS_API_KEY. Tests will be skipped if the API key is not set. API rate limits may apply.

Dependencies

• fastmcp: MCP server framework
• httpx: Async HTTP client for API requests
• python-dotenv: Environment variable management