MCP server (AI-native layer)

Exposes the Datavidence Financials API as MCP tools for LLM agents (Claude Desktop, LangChain, custom frameworks). It's a standalone component that forwards over HTTP to the REST API, so the core service keeps its pinned deps (the MCP SDK needs a much newer pydantic/uvicorn — see docs/13).

Install

Published on PyPI as datavidence-financials. Run it with no clone using uv — it installs into a throwaway environment:

FL_API_KEY=sandbox_demo_key uvx datavidence-financials

or install it as a persistent tool with pipx:

pipx install datavidence-financials
FL_API_KEY=sandbox_demo_key datavidence-financials

sandbox_demo_key returns sample data with no signup; set FL_API_KEY to your real key for live data (see Config below). The server speaks MCP over stdio, so an MCP client launches it — see the Claude Desktop setup below.

Tools

• get_financials — normalized income statement + balance sheet + cash flow for a company/year; supports as_of (point-in-time), include_provenance (per-value SEC source URLs), include_ratios.
• get_financials_batch — the same, for up to 25 companies in one call (comma-separated tickers/ciks); per-symbol results, counts as one quota unit.
• list_filings — recent SEC filings for a company (discover available years).
• get_usage — the key's monthly quota state (tier, used, remaining, reset); free to call, consumes no quota.

Errors surface the API's recovery_action, so agents self-correct.

Run it

python -m venv .venv && . .venv/bin/activate
pip install -r mcp_server/requirements.txt
FL_API_KEY=sandbox_demo_key python -m mcp_server.server   # stdio transport

sandbox_demo_key returns sample data with no signup — good for a first run. Swap in your real RapidAPI/AWS key for live data.

Config (env): FL_API_KEY (required), FL_API_BASE_URL (default the production origin), FL_API_KEY_HEADER (default X-API-Key), FL_API_TIMEOUT (default 30).

Claude Desktop

Recommended (published package): point Claude Desktop at the uvx launcher — no clone, no venv, no PYTHONPATH:

{
  "mcpServers": {
    "datavidence-financials": {
      "command": "uvx",
      "args": ["datavidence-financials"],
      "env": { "FL_API_KEY": "sandbox_demo_key" }
    }
  }
}

Fully quit (Cmd+Q) and reopen Claude Desktop; the tools appear. Swap in your real key for live data.

Quick setup (macOS): one command creates the venv, installs deps, verifies the tools, and registers the server with Claude Desktop (backs up + merges your existing config):

mcp_server/setup_claude_desktop.sh            # uses the sandbox key
mcp_server/setup_claude_desktop.sh <your-key> # or your real key

Then fully quit (Cmd+Q) and reopen Claude Desktop.

Manual: Add to claude_desktop_config.json (point command at the venv's python, and set the repo dir so mcp_server is importable):

{
  "mcpServers": {
    "datavidence-financials": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/absolute/path/to/financial-api",
      "env": { "FL_API_KEY": "sandbox_demo_key" }
    }
  }
}

Restart Claude Desktop; the two tools appear. Ask e.g. "get AAPL's FY2023 financials with ratios" to exercise get_financials.

Deployment note (docs/13 §2.1)

For a marketplace channel, set FL_API_BASE_URL to the gateway endpoint and FL_API_KEY/FL_API_KEY_HEADER to the gateway's key/header, so calls are metered by RapidAPI / AWS Data Exchange (BYOK) rather than hitting the locked origin directly. That's the M3 deployment step.