{
  "markdown": "<!-- mcp-name: com.hub-equity/hub-equity-mcp -->\n\n# hub-equity-mcp\n\n**Standardized XBRL financial data for LLM agents.** A Model Context Protocol (MCP)\nserver that exposes normalized financial facts from US SEC (EDGAR) and European\nESEF filings to Claude Desktop, Cursor, and any MCP-aware client.\n\nHub-Equity is the first MCP server to serve standardized **European ESEF** filings\nalongside US SEC data through one consistent hub-concept vocabulary, so an agent\ncan ask for `REVENUE` or `TOTAL_ASSETS` and get a comparable, source-linked value\nwhether the issuer files with the SEC or under ESEF.\n\n> **Maturity.** The data engine and public REST API behind this connector run in\n> production and power Hub-Equity's own chat. This PyPI package is the newly\n> published client for that API; the surface is stable (SemVer 1.0), but as a\n> distributed package it is fresh, hence the Beta classifier.\n\n## Why\n\n- **One vocabulary across two regimes.** SEC us-gaap and ESEF ifrs-full concepts\n  are mapped to a single set of standardized hub codes, so cross-issuer and\n  cross-taxonomy comparison works out of the box.\n- **Every number is source-linked.** Facts carry their filing, period, and\n  provenance so an agent can cite rather than guess.\n- **Read-only and closed-world.** Every tool advertises `readOnlyHint=true`,\n  `idempotentHint=true`, `destructiveHint=false`, `openWorldHint=false` per the\n  MCP spec, so clients can reason about safety and caching without introspection.\n- **No database credentials.** The published package talks only to the public\n  REST API (`https://api.hub-equity.com`) over HTTPS. It never ships or requires\n  a Supabase or DB key.\n\n## Install\n\n```bash\npip install hub-equity-mcp\n```\n\nRequires Python 3.12 or newer.\n\n## Authentication and access\n\nThe server talks only to the public REST API. Two modes:\n\n- **Anonymous (no key).** Works out of the box, no account required. Gives the\n  base tool set (entity search, normalized facts, time series, segments,\n  screener, FX conversion, and more), capped at **60 requests per minute** per IP.\n- **With a `hubq_` key** (env var `HUBEQUITY_API_KEY`). Unlocks the Pro tools\n  (restatement diffs, calculation trees, cross-period compare, data-quality\n  grades, validation checks, extension concepts). On the Pro plan a key also\n  raises the limit to **300 requests per minute** (1000 on Enterprise). A key is\n  free to create from a Hub-Equity account (beta). Paid Pro and Enterprise plans\n  exist but are not billed at this stage.\n\nThe published package never reaches the database directly, only the REST API.\n\n## Configure your client\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`\n(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`,\nWindows: `%APPDATA%\\Claude\\claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"hub-equity\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"hub_equity_mcp.server\"],\n      \"env\": {\n        \"HUBEQUITY_API_KEY\": \"hubq_live_...\"\n      }\n    }\n  }\n}\n```\n\nOmit `HUBEQUITY_API_KEY` to run anonymously (60 requests per minute, base tools only).\n\n### Cursor\n\nAdd to `.cursor/mcp.json` (project root) or the global Cursor MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"hub-equity\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"hub_equity_mcp.server\"],\n      \"env\": {\n        \"HUBEQUITY_API_KEY\": \"hubq_live_...\"\n      }\n    }\n  }\n}\n```\n\n### Environment variables\n\n- `HUBEQUITY_API_KEY` (optional): a `hubq_` key for premium tools and the higher\n  rate limit. Absent means anonymous mode.\n- `HUBEQUITY_API_URL` (optional): defaults to `https://api.hub-equity.com`.\n  `https://` is enforced whenever a key is set (the server refuses to send the\n  Bearer key over plaintext to a non-loopback host).\n\n## Capabilities\n\n| Type | Count |\n|---|---|\n| Tools | 19 (13 Free, 6 Pro) |\n| Resources | 9 (7 static, 2 URI templates) |\n| Prompts | 8 analytical templates |\n| Completion API | `{hub_code}` autocomplete |\n\n## Tools\n\nThe machine-readable tier catalog is served as a resource\n(`hub-equity://catalog/tool-tiers`). Free tools cover discovery and identity;\nPro tools add forensic depth (calculation trees, restatement diffs, cross-period\ncomparison, quality grades, validation results, extension concepts).\n\n| Tool | Tier | What it does |\n|---|---|---|\n| `find_entity(query)` | Free | Search by name, ticker, or CIK. Returns the `entity_id` other tools need. |\n| `get_fact(entity_id, code, fiscal_year, period_type)` | Free | One normalized value plus its filing source. |\n| `get_fact_decomposition(entity_id, code, fiscal_year, depth)` | Free (depth 1) / Pro (depth 2-3) | Hub rollup, XBRL calc-linkbase children, and dimensional breakdown. |\n| `search_concept(query)` | Free | Resolve a hub code from a label or XBRL qname. |\n| `list_hubs(category?, ...)` | Free | Enumerate the standardized hub catalog by category. |\n| `get_entity_profile(entity_id)` | Free | Sector, auditor, employees, fiscal year end, recent filings. |\n| `get_metric_history(entity_id, code, n_years)` | Free | N-year time series with YoY growth and CAGR. |\n| `get_segments(entity_id, code, fiscal_year)` | Free | Dimensional axis/member breakdown (segment, geography). |\n| `get_amendments(entity_id, fiscal_year?)` | Free | 10-K/A restatement summary. |\n| `compare_entities(ids, codes, fiscal_year)` | Free (up to 3x5) / Pro (up to 10x10) | Cross-issuer comparison matrix at one period. |\n| `roll_up_metric(entity_id, code, fiscal_year)` | Free | Compute a value from signed children when it is not directly tagged. |\n| `convert_currency(amount, from, to, date?, rate_type?)` | Free | ECB reference-rate FX conversion (closing, average YTD, average prior year). |\n| `screen_companies(filters, sort, limit)` | Free (limit 20, no quality filter) / Pro (higher) | Filter the issuer universe by metadata, revenue, audit, and data quality. |\n| `get_amendment_diff(entity_id, fiscal_year?, code?, min_diff_pct)` | Pro | Per-concept restatement diffs with a materiality filter. |\n| `compare_filings(entity_id, fy_a, fy_b, codes?)` | Pro | Cross-period same-entity compare with new / removed / sign-flip / restatement flags. |\n| `get_filing_calc_tree(filing_id, link_role?, statement?)` | Pro | Full presentation tree of a single filing. |\n| `get_extension_concepts(entity_id, status_filter?, limit?)` | Pro | Issuer-specific qnames declared outside standard taxonomies. |\n| `get_data_quality_grade(entity_id)` | Pro | A+ to D grade, coverage, freshness, direct-vs-derived breakdown. |\n| `get_validation_results(filing_id?, entity_id?, fiscal_year?, status?)` | Pro | XBRL accounting and calculation-linkbase checks. |\n\n## Resources\n\n| URI | Type | Purpose |\n|---|---|---|\n| `hub-equity://catalog/hubs` | json | Full standardized hub catalog with EN/FR labels and category. |\n| `hub-equity://catalog/categories` | json | Hub counts per category. |\n| `hub-equity://catalog/tool-tiers` | markdown | Free vs Pro tool catalog and gating conditions. |\n| `hub-equity://schema/financial-statements` | markdown | Statement structure and reading rules. |\n| `hub-equity://catalog/hub/{hub_code}` | template | Forward catalog entry for one hub. |\n| `hub-equity://entity/{entity_id}/profile` | template | Full entity snapshot. |\n| `hub-equity://prompts/best-practices` | markdown | System-prompt guidance for client integrations. Load this before calling any tool. |\n| `hub-equity://prompts/tool-usage-examples` | markdown | Per-tool few-shot examples (good and anti-pattern). |\n| `hub-equity://prompts/data-coverage` | json | Live dataset snapshot (issuer and filing counts, sources, taxonomies, fiscal year range). Cached 24h. |\n\n## Prompts\n\nEight analytical templates: `peer_comparison`, `quality_of_earnings`,\n`restatement_audit`, `sector_overview`, `valuation_screen`,\n`goodwill_impairment_risk`, `working_capital_diagnostic`, `cash_flow_consistency`.\n\n## For client developers\n\nBefore calling any tool, fetch `hub-equity://prompts/best-practices` and inject\nthe markdown into your system prompt. This makes your client follow the same tool\nrouting, source-citation, and numeric-fidelity rules as Hub-Equity's own chat.\n\n```python\n# Pseudo-code for a typical MCP client integration\nsession = mcp.connect(\"hub-equity-mcp\")\nbest_practices = session.read_resource(\"hub-equity://prompts/best-practices\")\nsystem_prompt = \"You are an assistant ...\\n\\n\" + best_practices\n# now call session.call_tool(\"find_entity\", {\"query\": \"AAPL\"}) etc.\n```\n\n## Rate limits\n\n| Mode | Limit | Notes |\n|---|---|---|\n| Anonymous or Free key | 60 requests / minute | Base tools. |\n| Pro key | 300 requests / minute | Unlocks Pro tools. |\n| Enterprise key | 1000 requests / minute | Unlocks Pro tools. |\n\nOn a 429 the client retries with exponential backoff (up to 3 times) before\nraising `RateLimitExceeded`.\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| `429 Too Many Requests` / `RateLimitExceeded` | Rate cap hit (60/min anon or Free, 300/min Pro) | Add a `HUBEQUITY_API_KEY` on a Pro plan, or slow down the tool-call fan-out. The client already backs off up to 3 times. |\n| `HubEquityRestError: HTTP 401` | Invalid or revoked `hubq_` key | Create a new key from your Hub-Equity account settings. |\n| `HubEquityRestError: HTTP 403` | Key lacks the scope for a Pro tool | Upgrade the plan, or use the base tool set. |\n| Connection or timeout errors | Network issue reaching `api.hub-equity.com`, or a bad `HUBEQUITY_API_URL` | Check connectivity; confirm `HUBEQUITY_API_URL` (if set) points to a reachable `https://` host. |\n| `ValueError: HUBEQUITY_API_URL must use https://` | A key is set but the URL is plain `http://` on a non-loopback host | Use `https://`, or unset `HUBEQUITY_API_URL` to fall back to the default API. |\n| Server does not appear in Claude Desktop or Cursor | Config JSON error, or `python` not on the client's PATH | Validate the JSON; use an absolute interpreter path if the client cannot resolve `python`. |\n\n## Run locally\n\n```bash\npython -m hub_equity_mcp.server\n```\n\nOr drive it interactively with the MCP inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector python -m hub_equity_mcp.server\n```\n\nThe inspector lists all 19 tools, 9 resources, and 8 prompts and lets you call\neach one.\n\n## Development\n\n```bash\npip install -e '.[dev]'\npytest tests/\n```\n\nTests are hermetic: tool tests mock the REST API with `respx`, so no live backend\nis needed.\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). This connector is an open\nclient to the public Hub-Equity REST API; access to premium data stays gated by\nAPI key, plan, and rate limits on the service side.\n",
  "bytes": 10607,
  "sha": "eb784a4a8cbb72f16639ca80d16f919e246fc4861d6dd55a7fb31a7fec94477d",
  "repo_slug": "hub-equity/hub-equity-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_hub_equity_hub_equity_mcp_04b34518/readme"
}