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 is the first MCP server to serve 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 data engine and public REST API behind this connector run in production and power Hub-Equity's own chat. This PyPI package is the newly published client for that API; the surface is stable (SemVer 1.0), but as a distributed package it is fresh, hence the Beta classifier.

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.
• 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 Supabase or DB key.

Install

pip install hub-equity-mcp

Requires Python 3.12 or newer.

Authentication and access

The server talks only to the public REST API. Two modes:

• Anonymous (no key). Works out of the box, no account required. Gives the base tool set (entity search, normalized facts, time series, segments, screener, FX conversion, and more), capped at 30 requests per minute per IP.
• With a hubq_ key (env var HUBEQUITY_API_KEY). Unlocks the Pro tools (restatement diffs, calculation trees, cross-period compare, data-quality grades, validation checks, extension concepts). On the Pro plan a key also raises the limit to 300 requests per minute (1000 on Enterprise). A key is free to create from a Hub-Equity account (beta). Paid Pro and Enterprise plans exist but are not billed at this stage.

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": "python",
      "args": ["-m", "hub_equity_mcp.server"],
      "env": {
        "HUBEQUITY_API_KEY": "hubq_live_..."
      }
    }
  }
}

Omit HUBEQUITY_API_KEY to run anonymously (30 requests per minute, base tools only).

Cursor

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

{
  "mcpServers": {
    "hub-equity": {
      "command": "python",
      "args": ["-m", "hub_equity_mcp.server"],
      "env": {
        "HUBEQUITY_API_KEY": "hubq_live_..."
      }
    }
  }
}

Environment variables

• HUBEQUITY_API_KEY (optional): a hubq_ key for premium tools and the higher rate limit. Absent means anonymous mode.
• 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 add forensic depth (calculation trees, restatement diffs, cross-period comparison, quality grades, validation results, extension concepts).

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 principal, not per plan. Search and the listing endpoints keep a 30/minute ceiling for every caller, key or not.

On a 429 the client retries with exponential backoff (up to 3 times) before raising RateLimitExceeded.

Troubleshooting

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 all 19 tools, 9 resources, and 8 prompts 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.