> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatasets.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Access the official MCP server for Financial Datasets.

## Overview

Your AI assistant can use our official MCP server to access real-time financial data — stock prices, financials, SEC filings, news, and more.

## Authentication

The MCP server supports two authentication methods:

* **OAuth 2.1** — Used by interactive clients ([Claude](#claude), [Claude Code](#claude-code), [Cursor](#cursor), etc.). When you first connect, you'll be redirected to sign in with your Financial Datasets account. No API key is needed.

* **API Key** — Used for [programmatic](#python) access via the `https://mcp.financialdatasets.ai/api` endpoint. Include your key in the `X-API-KEY` header.

If you don't have an account, [sign up for free](https://financialdatasets.ai/register) to get started. You can generate an API key from your [account dashboard](https://financialdatasets.ai/).

## Getting Started

Choose your client below and follow the steps to connect.

<Tabs>
  <Tab title="Claude">
    These steps work for both **Claude.ai** (web) and the **Claude Desktop** app.

    1. Go to **Settings** → **Connectors**
    2. Click **Add** and enter the server URL: `https://mcp.financialdatasets.ai/`
    3. Click **Add custom connector** and complete OAuth authentication
    4. In any new chat, click **+** and enable **Financial Datasets** under Connectors

    <Note>On Team and Enterprise plans, a workspace owner must add the connector in Admin settings first.</Note>
  </Tab>

  <Tab title="Claude Code">
    Run the following command in your terminal:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    claude mcp add --transport http financial-datasets https://mcp.financialdatasets.ai/
    ```

    Then authenticate by typing `/mcp` inside Claude Code and completing the OAuth flow in your browser.

    You can verify the server is connected at any time:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    claude mcp list
    ```
  </Tab>

  <Tab title="Claude Managed Agents">
    For production agents built on Anthropic's hosted Managed Agents platform, authenticate with your API key using a `static_bearer` vault credential.

    1. Generate an API key from your [account dashboard](https://financialdatasets.ai).
    2. Create a `static_bearer` vault credential pointing at our `/api` endpoint:

    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {
      "type": "static_bearer",
      "mcp_server_url": "https://mcp.financialdatasets.ai/api",
      "token": "your-api-key"
    }
    ```

    3. Reference the vault ID when creating a session. Anthropic injects `Authorization: Bearer <your-api-key>` on every MCP call.

    See Anthropic's [vault credentials docs](https://platform.claude.com/docs/en/managed-agents/vaults) for full SDK examples in Python, TypeScript, Go, and Java.
  </Tab>

  <Tab title="Python">
    For scripts, notebooks, and custom MCP integrations, connect to the `/api` endpoint with your API key.

    Install the MCP Python SDK:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install mcp
    ```

    Connect, then call a tool — here we fetch the latest price for Apple:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import asyncio
    from mcp import ClientSession
    from mcp.client.streamable_http import streamablehttp_client

    API_KEY = "your-api-key"
    SERVER_URL = "https://mcp.financialdatasets.ai/api"

    async def main():
        # Open an authenticated connection to the MCP server
        async with streamablehttp_client(
            SERVER_URL,
            headers={"X-API-KEY": API_KEY},
        ) as streams:
            read_stream, write_stream, _ = streams

            # Start an MCP session
            async with ClientSession(read_stream, write_stream) as session:
                await session.initialize()

                # Call any tool from the MCP Tools list
                result = await session.call_tool(
                    "get_stock_price",
                    {"ticker": "AAPL"},
                )
                print(result.content)

    asyncio.run(main())
    ```

    Generate an API key from your [account dashboard](https://financialdatasets.ai/).
  </Tab>

  <Tab title="Cursor">
    Add the following to your `~/.cursor/mcp.json` file:

    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {
      "mcpServers": {
        "financial-datasets": {
          "url": "https://mcp.financialdatasets.ai/"
        }
      }
    }
    ```

    Save the file and restart Cursor. The agent automatically detects all available tools and calls the relevant one when you ask financial data questions in chat.
  </Tab>
</Tabs>

## MCP Tools

Once connected, your AI assistant will have access to the following tools:

**Beneficial Ownership**

* **`get_beneficial_owners`**: List beneficial owners (holders of more than 5% of a company's shares, from SEC Schedules 13D/13G) with their filer CIK and name. Optionally filter by name prefix. Use this to discover the `filer_cik` to pass to `get_beneficial_ownership`.
* **`get_beneficial_ownership`**: Get 5%+ beneficial-ownership stakes from SEC Schedules 13D and 13G. Query by `ticker` (who owns this company) or by `filer_cik` (what stakes does this owner hold). Use `type=activist` for Schedule 13D activist stakes or `type=passive` for 13G stakes; `history=true` returns each stake's full amendment chain instead of its current state.

**Company Information**

* **`get_company_facts`**: Get company details including employee count, sector, industry, exchange, and more.

**Earnings**

* **`get_earnings`**: Get earnings data from SEC filings. Both modes return a flat list of `EarningsRecord` entries — same shape in either mode. With `ticker`, returns the most recent SEC filings (8-K / 10-Q / 10-K / 20-F) for that company. Without `ticker`, returns the most recently filed earnings across all covered companies (the real-time feed). Each entry exposes `report_period`, `source_type`, `filing_date`, `accession_number`, plus `quarterly` and/or `annual` financial blocks.

**Financial Metrics**

* **`get_financial_metrics`**: Get historical financial metrics such as P/E ratio, enterprise value, and revenue per share.
* **`get_financial_metrics_snapshot`**: Get a snapshot of the latest financial metrics, including market cap, P/E ratio, and dividend yield.

**Financial Statements**

* **`get_income_statement`**: Get historical income statement data (revenue, expenses, net income).
* **`get_balance_sheet`**: Get historical balance sheet data (assets, liabilities, equity).
* **`get_cash_flow_statement`**: Get historical cash flow statement data (operating, investing, financing activities).

Each of these tools accepts an `as_reported` flag. Set `as_reported: true` to return the raw line items exactly as they appear in the company's filing, instead of our standardized fields. As-reported data supports only `annual` and `quarterly` periods (a `ttm` period is treated as `annual`).

**Index Funds**

* **`get_index_fund`**: Get an ETF or index fund's holdings and each position's weight (percent of net assets) for a fund ticker (e.g., SPY). Returns the fund's latest filing by default, or the composition as of a past date via `as_of`; optionally filter by `asset_class`.

**Insider Ownership**

* **`get_insider_ownership`**: Get insider ownership statements for a company: what officers, directors, and 10% owners actually hold (common shares, options, RSUs), from SEC Forms 3 and 5. Complements `get_insider_trades` — trades are the events, ownership statements are the state. Filter by insider `name` or `form_type` (`3` for initial statements, `5` for annual statements).

**Insider Trades**

* **`get_insider_trades`**: Get insider trading transactions for a company, including purchases, sales, and other transactions by officers, directors, and major shareholders.

**Institutional Holdings**

* **`get_institutional_investors`**: List institutional investors (SEC 13F filers) with their CIK and most recent reported name. Optionally filter by case-insensitive name prefix to discover the `filer_cik` to pass to `get_institutional_holdings`.
* **`get_institutional_holdings`**: Get SEC 13F institutional holdings sourced directly from EDGAR. Query by `filer_cik` (what positions a filer holds) or by `ticker` (which institutional filers hold this security). Defaults to the latest available quarter; optional `report_period`, `report_period_gte`, and `report_period_lte` filters narrow the range.

**Interest Rates**

* **`get_interest_rates`**: Get the latest policy interest rates from major central banks (e.g., FED, ECB, BOE, BOJ). Returns a snapshot of each bank's current rate — no parameters required.

**Key Performance Indicators**

* **`get_kpi_guidance`**: Get forward-looking KPI guidance items issued by management in earnings releases and filings. Filter by ticker, period, metric name, and date range.
* **`get_kpi_metrics`**: Get historical KPI taxonomy metrics extracted from SEC filings (e.g., subscriber counts, ARPU, units sold). Filter by ticker, period (quarterly/annual), metric name, and date range.
* **`get_kpi_non_gaap`**: Get non-GAAP KPIs reported by companies (e.g., Adjusted EBITDA, Free Cash Flow as defined by the company). Filter by ticker, period, metric name, and date range.

<Note>KPI data is available to Pro and Enterprise customers only.</Note>

**News**

* **`get_news`**: Get recent news articles for a specific company or the broad market. Pass a ticker for company-specific news, or omit the ticker for general market news.

**SEC Filings**

* **`get_filings`**: Get a list of historical SEC filings for a company (10-K, 10-Q, 8-K, and more).
* **`get_filing_items`**: Extract specific sections from 10-K, 10-Q, and 8-K filings (e.g., Risk Factors, MD\&A).
* **`list_filing_item_types`**: Get a list of all extractable items for 10-K, 10-Q, and 8-K filings.

**Segmented Financials**

* **`get_segmented_financials`**: Get segment breakdowns from all three financial statement types (income statement, balance sheet, cash flow) in a single call. Returns revenue, operating income, and depreciation by product/segment; assets, goodwill, and long-lived assets by segment; and capital expenditure by segment.

**Stock Prices**

* **`get_stock_prices`**: Get historical stock price data (open, high, low, close, volume) over a date range with configurable intervals.
* **`get_stock_price`**: Get the latest price snapshot for a stock, including current price and OHLCV data.

**Stock Screener**

* **`screen_stocks`**: Screen and filter stocks by financial metrics, valuation ratios, and company attributes. Combine multiple conditions to find stocks matching your criteria (e.g., revenue > \$1B, P/E \< 20, sector = "Technology").
* **`list_stock_screener_filters`**: Get a list of all available filter fields and operators for the stock screener, grouped by category.

## Example Usage

After connecting, try asking your AI assistant questions like:

* "What is Apple's current P/E ratio and market cap?"
* "Show me Tesla's income statement for the last 4 quarters"
* "Show me Apple's as-reported balance sheet from its latest annual filing"
* "How has Bitcoin's price changed over the past year?"
* "Break down Amazon's revenue by business segment"
* "What are SPY's top holdings and their weights?"
* "Find the Risk Factors section from Microsoft's latest 10-K"
* "Compare Google and Meta's revenue growth over the past 3 years"
* "Screen for technology stocks with a P/E ratio under 20 and revenue over \$1 billion"
* "What's happening in the markets today?"
* "What companies just reported earnings?"
* "Show me the latest earnings for Netflix"
* "What are the current central bank interest rates?"
* "Are there any activist investors in BlackBerry?"
* "What stakes does Saba Capital currently hold?"
* "What did Apple's newest insider own when they joined?"