FinancialFilings

English | 简体中文

FinancialFilings MCP Server

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. 17 curated tools by default (set MCP_FULL_SURFACE=1 for the full 55-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.

Or install the plugin, which adds the same server plus the financial-filings-research skill (tool cheat-sheet and research workflows):

/plugin install financialfilings --marketplace financial-reports/financial-reports-mcp-server

On Claude Code before 2.1.275, add the marketplace first: /plugin marketplace add financial-reports/financial-reports-mcp-server, then /plugin install financialfilings@financialfilings. Either way, run /mcp once to 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

One-click install from Cursor Directory, or add it by hand to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "financialfilings": { "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

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

Set MCP_FULL_SURFACE=1 to restore the full 55-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, per-exchange security listings, the agent account-onboarding endpoints (sign-up, key claim, key rotation, checkout link, owner confirmation, status), the raw filings_markdown_search_retrieve endpoint behind filings_markdown_search, and filings_document_retrieve (returns a file, not JSON).

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.            │
│  17 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 17-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.

Account

• usage_retrieve — Get API Usage and Spend

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.md
make dev               # creates .venv, installs, validates env, regenerates, serves on :8000
# MCP endpoint: http://localhost:8000/mcp

Or step by step:

# 1. Setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt -r requirements-test.txt

# 2. Configure
cp .env.example .env  # then fill in Cognito values; see docs/SELF-HOSTING.md

# 3. Generate the MCP module from the OpenAPI schema
python scripts/generate_mcp_tools.py

# 4. Run tests
pytest

# 5. Run locally
python -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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    MCP_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):

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

3. Point Claude Code at the local instance:

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

   Add it per developer like this rather than to the repo's .mcp.json: that file lists the production server only, because directories that scan this repo (e.g. Cursor Directory) advertise every entry in it as a public install.

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 changes
python scripts/generate_mcp_tools.py

# Run only fast unit tests
pytest 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
• Listed on: Claude connector directory, Cursor Directory
• 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 PTE. LTD.

---

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.