FinancialFilings

FinancialFilings MCP Server

[License: MIT] [Python] [MCP Spec] [Status]

Official Model Context Protocol (MCP) server for the FinancialFilings API. Direct access from Claude (and any MCP-compatible client) to regulatory filings, financial data, and corporate information from listed companies worldwide. 16 curated tools by default (set MCP_FULL_SURFACE=1 for the full 46-tool surface). Free for any FinancialFilings account. Sourced from official regulators.

Quick start

If you're an analyst, researcher, or anyone who wants to ask Claude about public-company filings:

1. Create a free account at financialfilings.com — the MCP connector is free for any FinancialFilings user. No paid plan required.
2. Add the connector in your MCP client — pick yours under Connect your client below. The two most common:
   • Claude.ai / Claude Desktop: Settings → Connectors → Add custom connector → URL: https://mcp.financialfilings.com/mcp
   • Claude Code: claude mcp add --transport http financialreports https://mcp.financialfilings.com/mcp
3. Sign in with your FinancialFilings account when prompted. That's it.

Full setup walkthrough with screenshots: financialfilings.com/integrations/claude/.

Connect your client

This is a remote MCP server — Streamable HTTP with OAuth (PKCE + Dynamic Client Registration). There is no API key to copy and no secret to store: connecting opens a browser sign-in with your FinancialFilings account.

Endpoint: https://mcp.financialfilings.com/mcp

Find your client below. If it isn't listed, use the Generic block at the end — the endpoint and OAuth flow are identical everywhere; only the config file differs.

Claude.ai / Claude Desktop

Settings → Connectors → Add custom connector → URL: https://mcp.financialfilings.com/mcp. Sign in when prompted.

Claude Code

claude mcp add --transport http financialreports https://mcp.financialfilings.com/mcp

Run /mcp in-session to complete the browser sign-in.

Codex (OpenAI)

Codex uses TOML. Add to ~/.codex/config.toml (or a project .codex/config.toml):

[mcp_servers.financialreports]url = "https://mcp.financialfilings.com/mcp"

Then authenticate — Codex runs the OAuth browser flow for servers that support it:

codex mcp login financialreports

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{  "mcpServers": {    "financialreports": { "url": "https://mcp.financialfilings.com/mcp" }  }}

OAuth runs in the browser on first use.

Kilo Code

Project .kilocode/mcp.json (or the global MCP settings file):

{  "mcpServers": {    "financialreports": {      "type": "remote",      "url": "https://mcp.financialfilings.com/mcp"    }  }}

opencode

opencode.json:

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "financialreports": {      "type": "remote",      "url": "https://mcp.financialfilings.com/mcp",      "enabled": true    }  }}

Gemini CLI

~/.gemini/settings.json:

{  "mcpServers": {    "financialreports": { "httpUrl": "https://mcp.financialfilings.com/mcp" }  }}

Hermes

mcp_servers in your Hermes config (YAML):

mcp_servers:  financialreports:    url: "https://mcp.financialfilings.com/mcp"    auth: oauth

Generic (any MCP client)

Most MCP-aware harnesses accept a mcpServers object. Point it at the endpoint over Streamable HTTP:

{  "mcpServers": {    "financialreports": {      "type": "streamable-http",      "url": "https://mcp.financialfilings.com/mcp"    }  }}

Clients with native remote-MCP OAuth (Claude, Cursor, Windsurf, VS Code, opencode, Codex via codex mcp login) run the sign-in in a browser automatically. For OpenClaw and other MCP-aware harnesses, use this block with the connector URL and complete OAuth when prompted — see your client's own MCP configuration docs for the exact file location.

Troubleshooting: "Client Not Registered"

If signing in sends you to a page titled Client Not Registered — "The client ID … was not found in the server's client registry" — your client is presenting a registration this server no longer has.

Remove the connector and add it again. That is the only thing that resolves it, and it takes a few seconds:

Two things the error page itself doesn't tell you:

• It won't fix itself, and retrying won't help. Sign-in happens in your browser, so your client never learns it failed — it waits for a callback that never arrives and simply replays the same dead ID. Restarting doesn't help either: hosted connectors (ChatGPT, Claude.ai) keep the registration server-side, so only removing the connector clears it.
• Nothing is wrong with your account and no data is affected. Re-adding creates a fresh registration and everything works as before.

If you were affected on or after 14 July 2026: a cache failover dropped stored client registrations. Sign-ins have worked normally since — only connectors added before that date need the remove-and-re-add above.

What you get

16 LLM-callable tools by default — the curated surface analysts actually use:

Set MCP_FULL_SURFACE=1 to restore the full 46-tool surface: the ISIC section/division/group/class hierarchy, the rest of the reference data (countries, languages, sources, line-item definitions, filing history), per-user watchlists, webhook subscriptions, the company-merge audit feed, and per-exchange security listings.

The shipped surface is generated from a committed, reviewed snapshot of the FinancialFilings OpenAPI schema (scripts/openapi.snapshot.json, pinned via FR_PIN_SCHEMA=1 in CI and the Docker build), so it's deterministic and never drifts silently on a rebuild.

Companion skill

The repository ships an Agent Skill — financial-filings-research — that teaches Claude how to compose these tools into the workflows analysts actually run: company lookup, filing summarization, multi-company financial comparison, ISIC industry screening, and filings monitoring. It activates automatically when the user mentions a company name, ticker, ISIN, filing type, or financial metric.

Architecture

┌──────────────────┐     OAuth (PKCE + DCR)      ┌──────────────────┐│  Claude / MCP    │  ───────────────────────►   │  AWS Cognito     ││  client          │                              │  (user pool)     │└────────┬─────────┘                              └────────┬─────────┘         │  Streamable HTTP /mcp                           │         │  + bearer token                                 │         ▼                                                 │┌──────────────────┐     verify subscription tier          ││  This server     │  ───────────────────────────────────► ││  (FastAPI +      │                                       ▼│   FastMCP)       │     proxy bearer token         ┌──────────────────┐│                  │  ─────────────────────────►    │  api.            ││  16 tools        │                                │  financial-      ││  generated from  │                                │  reports.eu      ││  OpenAPI schema  │                                │  (first-party)   │└──────────────────┘                                └──────────────────┘

Key design decisions:

• Tools are generated, not hand-written. scripts/generate_mcp_tools.py reads the OpenAPI schema — pinned to a committed snapshot via FR_PIN_SCHEMA=1 in CI and the Docker build — and emits src/financial_reports_mcp.py. The default surface is curated to a focused 16-tool set; MCP_FULL_SURFACE=1 emits the full surface. Note that _PRUNED_EXCLUDE in the generator is a denylist, so a new upstream endpoint joins the curated surface unless the snapshot-refresh PR explicitly excludes it.
• Bearer-token proxy, not session storage. The user's Cognito access token is forwarded to the upstream API on every call. No conversation data, no API responses cached server-side.
• Subscription gating in-process. A 15-second LRU cache holds Cognito sub → tier mappings to avoid hammering the FR API on every tool call.
• Same-origin asset proxy. /favicon.ico, /icon.png, /icon-{32,192,512}.png are served from this origin (proxied + cached from CDN) so connector UIs and the /consent page render without cross-origin CSP friction.

MCP spec compliance

Compliant with the MCP 2025-11-25 specification:

• ✅ Streamable HTTP transport — POST /mcp with MCP-Protocol-Version echo, 400 on unsupported versions
• ✅ OAuth 2.0 — RFC 7591 dynamic client registration + PKCE S256
• ✅ RFC 9728 protected-resource metadata — both at /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp
• ✅ Tool annotations — every tool has title plus readOnlyHint or destructiveHint
• ✅ outputSchema — six structured-content tools (companies_list, companies_retrieve, companies_financials_retrieve, filings_list, filings_retrieve, isins_list)
• ✅ Origin validation — 403 on unrecognized origins, 401 with proper WWW-Authenticate header for unauthenticated requests
• ✅ Multi-size connector icons — 32×32, 192×192, 512×512 PNG advertised in initialize response

CI verifies all of the above on every PR.

Tool catalog

The list below is regenerated by scripts/generate_mcp_tools.py on every build. Do not hand-edit between the markers.

Companies

• companies_financials_retrieve — Retrieve Company Financials
• companies_list — List Companies
• companies_next_annual_report_retrieve — Predict Next Annual Report
• companies_resolve_create — Resolve Companies by Identifier (Batch)
• companies_retrieve — Retrieve Company Details

Filing Categories

• filing_categories_list — List Filing Categories

Filing Types

• filing_types_list — List Filing Types

Filings

• filings_list — List Filings
• filings_markdown_retrieve — Retrieve Filing Markdown
• filings_retrieve — Retrieve Filing Details

ISINs

• isins_list — List ISINs
• isins_retrieve — Retrieve ISIN

Example prompts

Once connected, try:

• "Find Apple's most recent 10-K and summarize the risk factors that changed year-over-year."
• "Get full company details for ASML."
• "Compare net debt for Iberdrola, Engie, Enel, RWE for the latest fiscal year."
• "List EU airlines that filed annual reports in the last 6 months."
• "Show me insider-transaction filings at Tesla in the last 30 days."
• "Alert me when any company in my watchlist files an 8-K."
• "What's the LEI for Volkswagen AG?"

Self-hosting

Self-hosting requires standing up your own AWS Cognito user pool and is primarily useful for forking + adapting to a different upstream API. For the FinancialFilings API specifically, the hosted server at mcp.financialfilings.com is the supported path.

Detailed self-hosting docs (Docker, Cognito setup, env vars, CDN/icon configuration): docs/SELF-HOSTING.md.

Development

One-shot bootstrap (venv → deps → env check → generate → run):

cp .env.example .env   # fill in Cognito values first; see docs/SELF-HOSTING.mdmake dev               # creates .venv, installs, validates env, regenerates, serves on :8000# MCP endpoint: http://localhost:8000/mcp

Or step by step:

# 1. Setuppython3 -m venv venvsource venv/bin/activatepip install -r requirements.txt -r requirements-test.txt
# 2. Configurecp .env.example .env  # then fill in Cognito values; see docs/SELF-HOSTING.md
# 3. Generate the MCP module from the OpenAPI schemapython scripts/generate_mcp_tools.py
# 4. Run testspytest
# 5. Run locallypython -m uvicorn src.financial_reports_mcp:app --host 0.0.0.0 --port 8000# MCP endpoint: http://localhost:8000/mcp

CI runs the full unit suite plus a Docker-Compose end-to-end test (with Redis) on every PR. See .github/workflows/ci.yml.

Local development with a personal API key

For iterating on the generator, tools, or prompts against a real backend without going through the Cognito OAuth dance every restart, the server supports a dev-only DEV_MODE_API_KEY env var. When set, JWT validation is skipped on the existing /mcp endpoint (both the subscription_required and _authorize_or_raise paths) and the key is forwarded as X-API-Key to API_BASE_URL.

This is a maintainer convenience, not a production auth path. The module refuses to import if MCP_BASE_URL contains a production hostname (mcp.financialfilings.com).

1. Add your personal FinancialFilings API key to .env:
   DEV_MODE_API_KEY=fr_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxMCP_BASE_URL=http://localhost:8000

2. Regenerate and start the server (Cognito vars must still be set — the OAuth proxy module loads even when the bypass is active):
   bash

   make regenpython -m uvicorn src.financial_reports_mcp:app --host 0.0.0.0 --port 8000 --reload

3. Point Claude Code at the local instance:
   bash

   claude mcp add --transport http financialreports-local http://localhost:8000/mcp

Production headless / API-key auth (parallel /mcp/apikey endpoint with per-request X-API-Key) is tracked in #28 and is a separate feature from this dev-mode shortcut.

Common tasks

# Regenerate tools after the OpenAPI schema changespython scripts/generate_mcp_tools.py
# Run only fast unit testspytest tests/test_*.py
# Run end-to-end tests with Redis (requires Docker)make e2e

Evaluating changes

This server is benchmarked by financial-reports/mcp-evals (private). Cross-model scorecards (task success, tool-selection accuracy, path consistency, tokens/turns/latency) live there, not here. Before merging changes to tool descriptions, Prompts, or the generator, run the harness against either prod or a local dev MCP and compare the scorecard.

What lives in this repo: deterministic prompt-registration tests at tests/eval/ — fast, no API keys, run on every PR. See tests/eval/README.md for the cross-repo workflow.

Security

This server handles OAuth flows and bearer tokens. Found a vulnerability? Please don't open a public issue. See SECURITY.md for the responsible-disclosure process.

Server-side guarantees:

• Bearer tokens are proxied per-request, never logged or persisted.
• HTTPS is enforced (HTTP redirects to HTTPS at the edge).
• CSP is applied to HTML responses (default-src 'none', only same-origin assets allowed).
• Origin validation rejects requests from unrecognized origins.
• All cryptographic operations rely on standard library + AWS SDKs; no custom crypto.

Contributing

Contributions welcome. See CONTRIBUTING.md for development setup, the regenerate→test→PR workflow, and what kinds of changes are welcome (tests, docs, generator improvements, hand-tuned tool descriptions in scripts/generate_mcp_tools.py) versus what gets rejected (hand-edited src/financial_reports_mcp.py — it's auto-generated and overwritten on every build).

Project status

• Production: live at https://mcp.financialfilings.com/mcp
• MCP Directory: submitted for inclusion (May 2026)
• Spec compliance: MCP 2025-11-25
• Tested with: Claude.ai, Claude Code, Claude Desktop, Cursor, Windsurf. Config snippets also provided for Codex, Kilo Code, opencode, Gemini CLI, and Hermes (see Connect your client).

License

MIT — © FinancialReports.

Acknowledgments

Special thanks to @itisaevalex for the original community-built MCP server, which served as the proof-of-concept that motivated this official version.

Built on FastMCP, FastAPI, and the Model Context Protocol.