> ## 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.

## Connect your client

Pick your client and follow the steps. Interactive clients sign you in automatically — no API key needed.

<Tabs>
  <Tab title="Claude">
    Works 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 sign-in
    4. In any new chat, click **+** and enable **Financial Datasets** under Connectors
  </Tab>

  <Tab title="Claude Code">
    Run this in your terminal:

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

    Then type `/mcp` inside Claude Code and complete sign-in in your browser. Verify anytime with `claude mcp list`.
  </Tab>

  <Tab title="ChatGPT">
    Install the official **Financial Datasets** plugin from ChatGPT's Plugin Directory.

    1. Open [Financial Datasets in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_69cacd9394a88191ba6564e1bb0430fa), or search for **Financial Datasets** in the Plugin Directory
    2. Click **Install plugin**, connect the Financial Datasets app, and complete sign-in
    3. In a new chat, mention `@Financial Datasets` or select it from **+** → **More**
  </Tab>

  <Tab title="Codex">
    Run these commands in your terminal:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    codex mcp add financial-datasets --url https://mcp.financialdatasets.ai/
    codex mcp login financial-datasets
    ```

    Complete sign-in in your browser. The server is then available in the Codex app, CLI, and IDE extension. Verify anytime with `codex mcp list` or type `/mcp` in Codex.
  </Tab>

  <Tab title="Hermes">
    Add the server to `~/.hermes/config.yaml`:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    mcp_servers:
      financial-datasets:
        url: "https://mcp.financialdatasets.ai/"
        auth: oauth
    ```

    Then run OAuth sign-in from a fresh terminal (don't start it from inside an already-running Hermes session — the auto-reload timeout is too short for browser auth):

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    hermes mcp login financial-datasets
    ```

    Complete sign-in in your browser. In an active Hermes session, reload MCP tools with `/reload-mcp`, or start a new chat:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    hermes chat
    ```

    See Hermes' [MCP docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) for filtering, re-auth, and troubleshooting.
  </Tab>

  <Tab title="OpenClaw">
    Add the Financial Datasets MCP server to OpenClaw, then complete OAuth sign-in:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    openclaw mcp add financial-datasets \
      --url https://mcp.financialdatasets.ai/ \
      --transport streamable-http \
      --auth oauth

    openclaw mcp login financial-datasets
    ```

    OpenClaw prints an authorization URL — approve in your browser, then finish with:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    openclaw mcp login financial-datasets --code <code>
    ```

    Verify the connection anytime with:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    openclaw mcp probe financial-datasets
    ```

    Prefer editing config by hand? Add this under `mcp.servers` in `~/.openclaw/openclaw.json`, then run the same `openclaw mcp login` flow:

    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {
      "mcp": {
        "servers": {
          "financial-datasets": {
            "url": "https://mcp.financialdatasets.ai/",
            "transport": "streamable-http",
            "auth": "oauth"
          }
        }
      }
    }
    ```

    See OpenClaw's [MCP docs](https://docs.openclaw.ai/cli/mcp) for full CLI and config reference.
  </Tab>

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

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

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

## Programmatic access

Building a script or a production agent? Connect to the `https://mcp.financialdatasets.ai/api` endpoint with an API key ([sign up free](https://financialdatasets.ai/register), then generate a key in your [dashboard](https://financialdatasets.ai/)).

<Tabs>
  <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())
    ```
  </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>
</Tabs>

## Available tools

<Accordion title="Browse all 30+ 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 on all paid plans.</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.
</Accordion>

## Example prompts

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"
* "Screen for technology stocks with a P/E under 20 and revenue over \$1 billion"
* "Find the Risk Factors section from Microsoft's latest 10-K"
* "Are there any activist investors in BlackBerry?"
* "What companies just reported earnings today?"