{"id":49837134,"url":"https://github.com/financial-reports/financial-reports-mcp-server","last_synced_at":"2026-05-14T01:38:45.942Z","repository":{"id":323854416,"uuid":"1094816269","full_name":"financial-reports/financial-reports-mcp-server","owner":"financial-reports","description":"Official Model Context Protocol (MCP) server for the FinancialReports API. Provides LLM-native access to European company filings and financial data.","archived":false,"fork":false,"pushed_at":"2026-05-06T12:52:59.000Z","size":86,"stargazers_count":2,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T14:40:27.541Z","etag":null,"topics":["filing","filings","finance","fundamental-analysis","mcp","mcp-server","stocks","stocks-api","trading"],"latest_commit_sha":null,"homepage":"https://financialreports.eu/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/financial-reports.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-12T07:58:40.000Z","updated_at":"2026-05-06T12:53:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/financial-reports/financial-reports-mcp-server","commit_stats":null,"previous_names":["financial-reports/financial-reports-mcp-server"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/financial-reports/financial-reports-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/financial-reports%2Ffinancial-reports-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/financial-reports%2Ffinancial-reports-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/financial-reports%2Ffinancial-reports-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/financial-reports%2Ffinancial-reports-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/financial-reports","download_url":"https://codeload.github.com/financial-reports/financial-reports-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/financial-reports%2Ffinancial-reports-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33006636,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"ssl_error","status_checked_at":"2026-05-13T13:14:51.610Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filing","filings","finance","fundamental-analysis","mcp","mcp-server","stocks","stocks-api","trading"],"created_at":"2026-05-14T01:38:44.904Z","updated_at":"2026-05-14T01:38:45.937Z","avatar_url":"https://github.com/financial-reports.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FinancialReports MCP Server\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)\n[![MCP Spec](https://img.shields.io/badge/MCP-2025--11--25-green)](https://modelcontextprotocol.io)\n[![Status](https://img.shields.io/badge/status-production-green)](https://mcp.financialfilings.com/health)\n\n\u003e **Official Model Context Protocol (MCP) server for the [FinancialReports](https://financialreports.eu) API.**\n\u003e Direct access from Claude (and any MCP-compatible client) to regulatory filings, financial data, and corporate information from listed companies worldwide. **43 tools across 9 domains. Free for any FinancialReports account.** Sourced from official regulators.\n\n---\n\n## Quick start\n\nIf you're an analyst, researcher, or anyone who wants to ask Claude about public-company filings:\n\n1. **Create a free account** at [financialreports.eu](https://financialreports.eu/) — the MCP connector is free for any FinancialReports user. No paid plan required.\n2. **Add the connector** in your MCP client:\n   - **Claude.ai / Claude Desktop**: Settings → Connectors → Add custom connector → URL: `https://mcp.financialfilings.com/mcp`\n   - **Claude Code**: `claude mcp add --transport http financialreports https://mcp.financialfilings.com/mcp`\n   - **Cursor / Windsurf / other**: same URL, OAuth flow runs in the browser.\n3. **Sign in** with your FinancialReports account when prompted. That's it.\n\nFull setup walkthrough with screenshots: [financialreports.eu/integrations/claude/](https://financialreports.eu/integrations/claude/).\n\n---\n\n## What you get\n\n**43 LLM-callable tools** across nine domains:\n\n| Domain | Tools | Use cases |\n|---|---|---|\n| Companies | 4 | Search by name/ticker/ISIN, retrieve full company profiles, get normalized financials, predict next annual report |\n| Filings | 5 | List, retrieve, fetch markdown content (capped at 150K chars), audit trail, \"live pulse\" of recent filings across all issuers |\n| ISINs | 2 | Lookup by ISIN, list dual-listings |\n| ISIC industry classifications | 8 | Section/division/group/class hierarchy for industry screening |\n| Reference data | 8 | Countries, languages, sources (regulators), filing categories, filing types |\n| Financial data | 2 | Normalized line-item definitions across regulators |\n| Watchlist | 4 | Per-user company watchlist (single + bulk operations) |\n| Webhooks | 8 | Filing-event subscriptions, delivery logs, replay, secret rotation |\n\nAll tools are auto-generated from the [FinancialReports OpenAPI schema](https://financialreports.eu/api/schema/) so the MCP surface never drifts from the underlying API.\n\n### Companion skill\n\nThe repository ships an [Agent Skill](skills/financial-filings-research/) — `financial-filings-research` — that teaches Claude how to compose these 43 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.\n\n---\n\n## Architecture\n\n```\n┌──────────────────┐     OAuth (PKCE + DCR)      ┌──────────────────┐\n│  Claude / MCP    │  ───────────────────────►   │  AWS Cognito     │\n│  client          │                              │  (user pool)     │\n└────────┬─────────┘                              └────────┬─────────┘\n         │  Streamable HTTP /mcp                           │\n         │  + bearer token                                 │\n         ▼                                                 │\n┌──────────────────┐     verify subscription tier          │\n│  This server     │  ───────────────────────────────────► │\n│  (FastAPI +      │                                       ▼\n│   FastMCP)       │     proxy bearer token         ┌──────────────────┐\n│                  │  ─────────────────────────►    │  api.            │\n│  43 tools        │                                │  financial-      │\n│  generated from  │                                │  reports.eu      │\n│  OpenAPI schema  │                                │  (first-party)   │\n└──────────────────┘                                └──────────────────┘\n```\n\n**Key design decisions:**\n\n- **Tools are generated, not hand-written.** `scripts/generate_mcp_tools.py` reads the live OpenAPI schema and emits `src/financial_reports_mcp.py`. Adding an endpoint to the API automatically gives Claude a new tool on the next regen.\n- **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.\n- **Subscription gating in-process.** A 15-second LRU cache holds Cognito `sub` → tier mappings to avoid hammering the FR API on every tool call.\n- **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.\n\n---\n\n## MCP spec compliance\n\nCompliant with the [MCP 2025-11-25 specification](https://modelcontextprotocol.io/specification/2025-11-25):\n\n- ✅ **Streamable HTTP transport** — `POST /mcp` with `MCP-Protocol-Version` echo, 400 on unsupported versions\n- ✅ **OAuth 2.0** — RFC 7591 dynamic client registration + PKCE S256\n- ✅ **RFC 9728 protected-resource metadata** — both at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-protected-resource/mcp`\n- ✅ **Tool annotations** — every tool has `title` plus `readOnlyHint` or `destructiveHint`\n- ✅ **`outputSchema`** — six structured-content tools (`companies_list`, `companies_retrieve`, `companies_financials_retrieve`, `filings_list`, `filings_retrieve`, `isins_list`)\n- ✅ **Origin validation** — 403 on unrecognized origins, 401 with proper `WWW-Authenticate` header for unauthenticated requests\n- ✅ **Multi-size connector icons** — 32×32, 192×192, 512×512 PNG advertised in `initialize` response\n\nCI verifies all of the above on every PR.\n\n---\n\n## Tool catalog\n\nThe list below is regenerated by `scripts/generate_mcp_tools.py` on every build. Do not hand-edit between the markers.\n\n\u003c!-- BEGIN AUTO-GENERATED TOOL LIST --\u003e\n\u003c!-- DO NOT EDIT BY HAND. Re-run scripts/generate_mcp_tools.py. --\u003e\n\n### Companies\n* `companies_financials_retrieve` — Retrieve Company Financials\n* `companies_list` — List Companies\n* `companies_next_annual_report_retrieve` — Predict Next Annual Report\n* `companies_retrieve` — Retrieve Company Details\n\n### Countries\n* `countries_list` — List Countries\n* `countries_retrieve` — Retrieve Country\n\n### Filing Categories\n* `filing_categories_list` — List Filing Categories\n* `filing_categories_retrieve` — Retrieve Filing Category\n\n### Filing Types\n* `filing_types_list` — List Filing Types\n* `filing_types_retrieve` — Retrieve Filing Type\n\n### Filings\n* `filings_history_retrieve` — Retrieve Filing History (Audit Trail)\n* `filings_list` — List Filings\n* `filings_markdown_retrieve` — Retrieve Filing Markdown\n* `filings_retrieve` — Retrieve Filing Details\n\n### Financial Data\n* `line_item_definitions_list` — List Line Item Definitions\n* `line_item_definitions_retrieve` — Retrieve Line Item Definition\n\n### ISIC Classifications\n* `isic_classes_list` — List ISIC Classes\n* `isic_classes_retrieve` — Retrieve ISIC Class\n* `isic_divisions_list` — List ISIC Divisions\n* `isic_divisions_retrieve` — Retrieve ISIC Division\n* `isic_groups_list` — List ISIC Groups\n* `isic_groups_retrieve` — Retrieve ISIC Group\n* `isic_sections_list` — List ISIC Sections\n* `isic_sections_retrieve` — Retrieve ISIC Section\n\n### ISINs\n* `isins_list` — List ISINs\n* `isins_retrieve` — Retrieve ISIN\n\n### Languages\n* `languages_list` — List Languages\n* `languages_retrieve` — Retrieve Language\n\n### Sources\n* `sources_list` — List Data Sources\n* `sources_retrieve` — Retrieve Data Source\n\n### Watchlist\n* `watchlist_companies_bulk_add_create` — Bulk Add Companies to Watchlist\n* `watchlist_companies_bulk_remove_create` — Bulk Remove Companies from Watchlist\n* `watchlist_companies_create` — Add Company to Watchlist\n* `watchlist_retrieve` — Get User's Watchlist\n\n### Webhooks (Management)\n* `webhooks_create` — Create Webhook\n* `webhooks_deliveries_replay_create` — Replay Delivery\n* `webhooks_deliveries_retrieve` — List Delivery Logs\n* `webhooks_delivery_detail_retrieve` — Retrieve Delivery Detail\n* `webhooks_list` — List Webhooks\n* `webhooks_regenerate_secret_create` — Regenerate Secret Key\n* `webhooks_retrieve` — Retrieve Webhook\n* `webhooks_test_create` — Test Webhook\n\n### filings\n* `filings_live_pulse_retrieve` — Filings Live Pulse Retrieve\n\n\u003c!-- END AUTO-GENERATED TOOL LIST --\u003e\n\n---\n\n## Example prompts\n\nOnce connected, try:\n\n- *\"Find Apple's most recent 10-K and summarize the risk factors that changed year-over-year.\"*\n- *\"Get full company details for ASML.\"*\n- *\"Compare net debt for Iberdrola, Engie, Enel, RWE for the latest fiscal year.\"*\n- *\"List EU airlines that filed annual reports in the last 6 months.\"*\n- *\"Show me insider-transaction filings at Tesla in the last 30 days.\"*\n- *\"Alert me when any company in my watchlist files an 8-K.\"*\n- *\"What's the LEI for Volkswagen AG?\"*\n\n---\n\n## Self-hosting\n\nSelf-hosting requires standing up your own AWS Cognito user pool and is primarily useful for forking + adapting to a different upstream API. For the FinancialReports API specifically, the hosted server at `mcp.financialfilings.com` is the supported path.\n\nDetailed self-hosting docs (Docker, Cognito setup, env vars, CDN/icon configuration): **[docs/SELF-HOSTING.md](docs/SELF-HOSTING.md)**.\n\n---\n\n## Development\n\n```bash\n# 1. Setup\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt -r requirements-test.txt\n\n# 2. Configure\ncp .env.example .env  # then fill in Cognito values; see docs/SELF-HOSTING.md\n\n# 3. Generate the MCP module from the OpenAPI schema\npython scripts/generate_mcp_tools.py\n\n# 4. Run tests\npytest\n\n# 5. Run locally\npython -m uvicorn src.financial_reports_mcp:app --host 0.0.0.0 --port 8000\n# MCP endpoint: http://localhost:8000/mcp\n```\n\nCI runs the full unit suite plus a Docker-Compose end-to-end test (with Redis) on every PR. See [`.github/workflows/ci.yml`](.github/workflows/ci.yml).\n\n### Common tasks\n\n```bash\n# Regenerate tools after the OpenAPI schema changes\npython scripts/generate_mcp_tools.py\n\n# Run only fast unit tests\npytest tests/test_*.py\n\n# Run end-to-end tests with Redis (requires Docker)\nmake e2e\n```\n\n---\n\n## Security\n\nThis server handles OAuth flows and bearer tokens. **Found a vulnerability? Please don't open a public issue.** See [SECURITY.md](SECURITY.md) for the responsible-disclosure process.\n\nServer-side guarantees:\n\n- Bearer tokens are proxied per-request, never logged or persisted.\n- HTTPS is enforced (HTTP redirects to HTTPS at the edge).\n- CSP is applied to HTML responses (`default-src 'none'`, only same-origin assets allowed).\n- Origin validation rejects requests from unrecognized origins.\n- All cryptographic operations rely on standard library + AWS SDKs; no custom crypto.\n\n---\n\n## Contributing\n\nContributions welcome. See [CONTRIBUTING.md](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).\n\n---\n\n## Project status\n\n- **Production**: live at `https://mcp.financialfilings.com/mcp`\n- **MCP Directory**: submitted for inclusion (May 2026)\n- **Spec compliance**: MCP 2025-11-25\n- **Tested with**: Claude.ai, Claude Code, Claude Desktop, Cursor, Windsurf\n\n---\n\n## License\n\n[MIT](LICENSE) — © FinancialReports.\n\n---\n\n## Acknowledgments\n\nSpecial thanks to [@itisaevalex](https://github.com/itisaevalex) for the [original community-built MCP server](https://github.com/itisaevalex/financial-reports-mcp-server), which served as the proof-of-concept that motivated this official version.\n\nBuilt on [FastMCP](https://github.com/jlowin/fastmcp), [FastAPI](https://fastapi.tiangolo.com/), and the [Model Context Protocol](https://modelcontextprotocol.io).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinancial-reports%2Ffinancial-reports-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffinancial-reports%2Ffinancial-reports-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinancial-reports%2Ffinancial-reports-mcp-server/lists"}