financial-reports-mcp-server

# FinancialFilings MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![MCP Spec](https://img.shields.io/badge/MCP-2025--11--25-green)](https://modelcontextprotocol.io)
[![Status](https://img.shields.io/badge/status-production-green)](https://mcp.financialfilings.com/health)

> **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. **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](https://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](#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/](https://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**](#generic-any-mcp-client) 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

```bash
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`):

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

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

```bash
codex mcp login financialreports
```

### Cursor

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

```json
{
  "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):

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

### opencode

`opencode.json`:

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

### Gemini CLI

`~/.gemini/settings.json`:

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

### Hermes

`mcp_servers` in your Hermes config (YAML):

```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:

```json
{
  "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:

| Client | What to do |
|---|---|
| **ChatGPT / OpenAI** | Settings → Connectors → remove **FinancialFilings** (listed as **FinancialReports** if you connected before the rename) → add it back with `https://mcp.financialfilings.com/mcp` and sign in again. |
| **Claude.ai / Claude Desktop** | Settings → Connectors → remove **FinancialFilings** (listed as **FinancialReports** if you connected before the rename) → re-add and sign in again. |
| **Claude Code / Codex / Cursor / opencode** | Remove and re-add the server (e.g. `claude mcp remove financialreports`, then re-add), or run the client's login command again (`codex mcp login financialreports`). |

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:

| Domain | Tools | Use cases |
|---|---|---|
| Companies | 5 | Search by name/ticker/ISIN, retrieve full company profiles, get normalized financials, predict next annual report, batch-resolve a list of identifiers to company IDs |
| Filings | 4 | List, retrieve, fetch markdown content (capped at 150K chars), keyword-search inside a single filing |
| ISINs | 2 | Lookup by ISIN, list dual-listings |
| Reference taxonomy | 2 | Filing categories and filing types |
| Guides | 3 | Filing-type taxonomy, ISIC industry classification, and markdown-fetch strategy — callable references for tool-only clients that can't read MCP resources |

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](https://financialreports.eu/api/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](skills/financial-filings-research/) — `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.
- **Su