FinancialFilings

English | 简体中文

FinancialFilings MCP Server

Official Model Context Protocol (MCP) server for the [FinancialFilings](https://financialfilings.com) 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. Official filings, as published.

---

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

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

Already added the server under the old name financialreports? Nothing to change, it keeps working: the name is a local label in your client and the server never sees it. New installs use financialfilings.

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 + P