datavidence-financials

Datavidence Financials — MCP Server

Normalized US-GAAP financial statements from SEC EDGAR — income statement, balance sheet, and cash flow — exposed as Model Context Protocol (MCP) tools for LLM agents (Claude Desktop, LangChain, and custom frameworks). Every value is traceable to its source SEC filing, and figures can be pulled as originally reported for any date (no look-ahead), for backtests.

This is the open-source, AI-native layer for the Datavidence Financials API — a standalone stdio server that forwards over HTTPS to the REST API (bring your own key). The connector is MIT-licensed; the underlying API is a commercial service.

Quick start (no clone)

Run it with uv — it installs into a throwaway environment:

FL_API_KEY=sandbox_demo_key uvx datavidence-financials

sandbox_demo_key returns sample data with no signup — good for a first run. Swap in your real key for live SEC data. Or install it as a persistent tool with pipx install datavidence-financials.

Claude Desktop

Add to claude_desktop_config.json, then fully quit (Cmd+Q) and reopen Claude Desktop — the tools appear:

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

Then ask, e.g., "get AAPL's FY2023 financials with ratios."

Tools

• get_financials — normalized income statement + balance sheet + cash flow for one company and fiscal year, from SEC EDGAR XBRL. Supports as_of (point-in-time, as originally reported), include_provenance (per-value SEC accession, filed date, and direct EDGAR source URL), and include_ratios (margins, ROA/ROE, leverage).
• get_financials_batch — the same, for up to 25 companies in one call (comma-separated tickers/CIKs). Per-symbol results; counts as a single quota unit, so one bad symbol never fails the batch.
• list_filings — a company's recent SEC filings (newest first) from the EDGAR submissions index; filter by form (e.g. 10-K). Use it to discover which fiscal years are available before calling get_financials.
• get_usage — the key's monthly quota (tier, used, remaining, reset). Free to call; consumes no quota.

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

Configuration (environment variables)

Variable	Default	Notes
FL_API_KEY	(none)	Your API key. sandbox_demo_key = no-signup trial (sample data).
FL_API_BASE_URL	https://api.financials.datavidence.ai	Point at a marketplace gateway for metered BYOK access.
FL_API_KEY_HEADER	X-API-Key	Header to send the key in (e.g. X-RapidAPI-Key for the RapidAPI gateway).
FL_API_TIMEOUT	30	Per-request timeout, in seconds.

Run from source

pip install -e .
FL_API_KEY=sandbox_demo_key python -m mcp_server.server   # stdio transport

Links

• API & docs: https://financials.datavidence.ai
• PyPI: https://pypi.org/project/datavidence-financials/
• Get a key (RapidAPI): https://rapidapi.com/datavidence-ykNLbvGmT/api/datavidence-financials-api
• Security: see SECURITY.md to report a vulnerability privately.

License

MIT © 2026 Datavidence LLC. The connector is open-source; the underlying Datavidence Financials API is a commercial service.