Hub-Equity MCP

SEC and European (ESEF) XBRL fundamentals on one concept vocabulary, every figure with its filing and the issuer's tag, amendments and silent restatements tracked. Read-only stdio server, Python.

GitHubTry this MCPSponsored

Documentation

hub-equity-mcp

Standardized XBRL financial data for LLM agents. A Model Context Protocol (MCP) server that exposes normalized financial facts from US SEC (EDGAR) and European ESEF filings to Claude Desktop, Cursor, and any MCP-aware client.

Hub-Equity serves standardized European ESEF filings alongside US SEC data through one consistent hub-concept vocabulary, so an agent can ask for REVENUE or TOTAL_ASSETS and get a comparable, source-linked value whether the issuer files with the SEC or under ESEF.

Maturity. The public REST API behind this connector runs in production and powers Hub-Equity's own chat. The package follows Semantic Versioning; it keeps the Beta classifier while its install base is young.

Why

One vocabulary across two regimes. SEC us-gaap and ESEF ifrs-full concepts are mapped to a single set of standardized hub codes, so cross-issuer and cross-taxonomy comparison works out of the box.
Every number is source-linked. Facts carry their filing, period, and provenance so an agent can cite rather than guess.
Restatement-aware. Explicit amendments and silent restatements (a figure a later filing reprinted differently, with no amendment filed), each change with the filing that made it.
Read-only and closed-world. Every tool advertises readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false per the MCP spec, so clients can reason about safety and caching without introspection.
No database credentials. The published package talks only to the public REST API (https://api.hub-equity.com) over HTTPS. It never ships or requires a database key.

Install

pipx run hub-equity-mcp

pipx run (or uvx hub-equity-mcp) fetches and starts the server in an isolated environment; pip install hub-equity-mcp works too. Requires Python 3.12 or newer.

Authentication and access

The server talks only to the public REST API, which needs a hubq_ key (env var HUBEQUITY_API_KEY).

Free key. Create an account and a key in a minute at https://hub-equity.com/settings/api-keys. Gives the base tool set (entity search, normalized facts, time series, segments, screener, data-quality grade, FX conversion, and more).
Paid plan. Unlocks the premium tools (restatement diffs, calculation trees, cross-period compare, cross-issuer compare, validation checks, extension concepts) and raises the rate limit. See the table below.

The published package never reaches the database directly, only the REST API.

Configure your client

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "hub-equity": {
      "command": "pipx",
      "args": ["run", "hub-equity-mcp"],
      "env": {
        "HUBEQUITY_API_KEY": "INSERT_YOUR_API_KEY"
      }
    }
  }
}

Without HUBEQUITY_API_KEY, every tool call answers HUBEQUITY_API_KEY is not set with the link to a Free key.

Cursor

Add to .cursor/mcp.json (project root) or the global Cursor MCP settings:

{
  "mcpServers": {
    "hub-equity": {
      "command": "pipx",
      "args": ["run", "hub-equity-mcp"],
      "env": {
        "HUBEQUITY_API_KEY": "INSERT_YOUR_API_KEY"
      }
    }
  }
}

Environment variables

HUBEQUITY_API_KEY (required): a hubq_ key. A Free key opens the base tools; a paid plan opens the premium tools and the higher rate limit.
HUBEQUITY_API_URL (optional): defaults to https://api.hub-equity.com. https:// is enforced whenever a key is set (the server refuses to send the Bearer key over plaintext to a non-loopback host).

Capabilities

Type	What
Tools	Read-only tools: discovery, facts, time series, segments, forensic checks (table below)
Resources	Hub catalog, statement schema, tier catalog, usage guides, coverage snapshot
Prompts	Analytical templates (list below)
Completion API	`{hub_code}` autocomplete

Tools

The machine-readable tier catalog is served as a resource (hub-equity://catalog/tool-tiers). Free tools cover discovery and identity; Pro tools, open on every paid plan (Builder, Team, Enterprise), add forensic depth (calculation trees, restatement diffs on amendments and silent restatements, cross-period comparison, cross-issuer comparison, validation results, extension concepts). The tier of a tool mirrors the REST endpoint it calls: every Pro tool's endpoint requires the facts.premium scope server-side, and the Free caps (get_fact_decomposition depth 1 without roll-up components or dimensional slices, screen_companies 20 results without the quality filter, get_segments axes without members, roll_up_metric the value without its rule) are applied by the API, not only by this package.

Tool	Tier	What it does
`find_entity(query)`	Free	Search by name, ticker, or CIK. Returns the `entity_id` other tools need.
`get_fact(entity_id, hub_concept_code, fiscal_year, fiscal_period_type?)`	Free	One normalized value plus its filing source.
`get_fact_decomposition(entity_id, fiscal_year, hub_concept_code? or qname?, depth?)`	Free (depth 1, linkbase only) / Pro (depth 2-3)	Hub rollup, XBRL calc-linkbase children, and dimensional breakdown. Free: the linkbase layer, without the roll-up components and the dimensional slices.
`search_concept(query)`	Free	Resolve a hub code from a label or a partial code.
`list_hubs(category?, include_non_primary?, limit?)`	Free	Enumerate the standardized hub catalog by category.
`get_entity_profile(entity_id)`	Free	Sector, auditor, employees, fiscal year end, recent filings.
`get_metric_history(entity_id, hub_concept_code, n_years?)`	Free	N-year time series with YoY growth and CAGR.
`get_segments(entity_id, hub_concept_code, fiscal_year)`	Free (capped)	Dimensional axis/member breakdown (segment, geography). Free: the axes without their members; Pro: every member.
`get_amendments(entity_id, fiscal_year?)`	Free	10-K/A restatement summary: every amendment, its per-concept changes (50 per amendment).
`get_silent_restatements(entity_id, fiscal_year?)`	Free	Silent restatements: figures a later filing reprinted differently in its comparative columns, with no amendment filed, grouped by the filing that revealed them (50 changes per filing).
`compare_entities(entity_ids, hub_concept_codes, fiscal_year)`	Pro (up to 10x10)	Cross-issuer comparison matrix at one period, calendar-year aligned. Accepts UUIDs, tickers or `TICKER.MIC`.
`roll_up_metric(entity_id, hub_concept_code, fiscal_year)`	Free (capped)	Compute a value from signed children when it is not directly tagged. Free: the value; Pro: the rule and the signed contributions behind it.
`convert_currency(amount, from_currency, to_currency, date?, rate_type?)`	Free	ECB reference-rate FX conversion (closing, average YTD, average prior year).
`screen_companies(country?, sector?, min_revenue?, ..., sort_by?, limit?)`	Free (limit 20, no quality filter) / Pro (higher)	Filter the issuer universe by metadata, revenue, audit, and data quality.
`get_amendment_diff(entity_id, fiscal_year?, hub_concept_code?, min_diff_pct?, kind_filter?)`	Pro	Per-concept 10-K/A diffs: materiality, kind and concept filters, label, absolute delta, both filings as sources.
`get_silent_restatement_diff(entity_id, fiscal_year?, hub_concept_code?, min_diff_pct?, kind_filter?)`	Pro	The same diff on the silent restatements.
`get_calculation_tree(filing_id, link_role?)`	Pro	The filing's calculation linkbase: every total and its components, declared sign next to the sign the filed values support.
`compare_filings(entity_id, fiscal_year_a, fiscal_year_b, hub_concept_codes?)`	Pro	Cross-period same-entity compare with new / removed / sign-flip / restatement flags.
`get_extension_concepts(entity_id, status_filter?, limit?)`	Pro	Issuer-specific qnames declared outside standard taxonomies.
`get_data_quality_grade(entity_id)`	Free	A+ to D grade (or none), the two gates and counts behind it, freshness, direct-vs-derived split.
`get_validation_results(filing_id?, entity_id?, fiscal_year?, status_filter?)`	Pro	XBRL accounting and calculation-linkbase checks.

Resources

URI	Type	Purpose
`hub-equity://catalog/hubs`	json	Full standardized hub catalog with EN/FR labels and category.
`hub-equity://catalog/categories`	json	Hub counts per category.
`hub-equity://catalog/tool-tiers`	markdown	Free vs Pro tool catalog and gating conditions.
`hub-equity://schema/financial-statements`	markdown	Statement structure and reading rules.
`hub-equity://catalog/hub/{hub_code}`	template	Forward catalog entry for one hub.
`hub-equity://entity/{entity_id}/profile`	template	Full entity snapshot.
`hub-equity://prompts/best-practices`	markdown	System-prompt guidance for client integrations. Load this before calling any tool.
`hub-equity://prompts/tool-usage-examples`	markdown	Per-tool few-shot examples (good and anti-pattern).
`hub-equity://prompts/data-coverage`	json	Live dataset snapshot (issuer and filing counts, sources, taxonomies, fiscal year range). Cached 24h.

Prompts

Eight analytical templates: peer_comparison, quality_of_earnings, restatement_audit, sector_overview, valuation_screen, goodwill_impairment_risk, working_capital_diagnostic, cash_flow_consistency.

For client developers

Before calling any tool, fetch hub-equity://prompts/best-practices and inject the markdown into your system prompt. This makes your client follow the same tool routing, source-citation, and numeric-fidelity rules as Hub-Equity's own chat.

# Pseudo-code for a typical MCP client integration
session = mcp.connect("hub-equity-mcp")
best_practices = session.read_resource("hub-equity://prompts/best-practices")
system_prompt = "You are an assistant ...\n\n" + best_practices
# now call session.call_tool("find_entity", {"query": "AAPL"}) etc.

Rate limits

Mode	Limit	Notes
Free key	120 requests / minute	Base tools.
Builder key	300 requests / minute	Premium tools unlocked.
Team key	600 requests / minute	Premium tools unlocked.
Enterprise key	1 000 requests / minute	Negotiable.

The bucket is per API key.

On a per-minute 429 the client retries with exponential backoff (up to 3 times) before raising RateLimitExceeded. A used-up daily or monthly allowance is raised at once, with the API's message.

Troubleshooting

Symptom	Cause	Fix
`429 Too Many Requests` / `RateLimitExceeded`	Rate cap hit (120/min with a Free key, 300 to 1 000/min on a paid key)	Move to a paid plan, or slow down the tool-call fan-out. The client already backs off up to 3 times.
`HUBEQUITY_API_KEY is not set` on every tool call	No key in the client's `env` block	Set `HUBEQUITY_API_KEY`; a Free key takes a minute at https://hub-equity.com/settings/api-keys.
`HubEquityRestError: HTTP 401`	An invalid, expired or revoked `hubq_` key (`INVALID_API_KEY`)	Create a new key at https://hub-equity.com/settings/api-keys.
`HubEquityRestError: HTTP 403`	The key's workspace is on the Free plan and the call needs a Pro tool, or a Free cap (`depth > 1`, `limit > 20`, `min_quality_grade`)	Upgrade the plan, or stay within the Free caps.
`RateLimitExceeded` whose body carries `DAILY_QUOTA_EXCEEDED` / `MONTHLY_QUOTA_EXCEEDED`	The workspace's volume allowance is used up (Free 200 a day / 5 000 a month, Builder 50 000, Team 500 000 a month); raised at once, without retry	Wait for `resets_on`, or upgrade the plan.
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.
`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.
Server does not appear in Claude Desktop or Cursor	Config JSON error, or `pipx` not on the client's PATH	Validate the JSON; use the absolute path of `pipx` (or `uvx`) if the client cannot resolve it.

Run locally

python -m hub_equity_mcp.server

Or drive it interactively with the MCP inspector:

npx @modelcontextprotocol/inspector python -m hub_equity_mcp.server

The inspector lists every tool, resource and prompt and lets you call each one.

Development

pip install -e '.[dev]'
pytest tests/

Tests are hermetic: tool tests mock the REST API with respx, so no live backend is needed.

License

Apache-2.0. See LICENSE and NOTICE. This connector is an open client to the public Hub-Equity REST API; access to premium data stays gated by API key, plan, and rate limits on the service side.