Hub-Equity MCP

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

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.

Resources

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

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

| 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