MCP Financial Datasets Server

# 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 ```bash cd mcp-financial-datasets uv sync ``` ## Usage ### Testing Locally ```bash mcp run -t sse financial_datasets_server.py:mcp ``` ### As Git Submodule ```bash 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 ```python income = await get_income_statements( ticker="AAPL", period="annual", limit=4, cutoff_date="2024-01-01" ) ``` ### Get Bitcoin Price History ```python 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 ```python 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 ## Dependencies - **fastmcp**: MCP server framework - **httpx**: Async HTTP client for API requests - **python-dotenv**: Environment variable management