QuantGist

QuantGist MCP Server

Exposes QuantGist macro-economic event data as Model Context Protocol (MCP) tools so Claude and other AI agents can query calendars, check event proximity, and assess trade safety — all within a conversation.

What it does

The server registers 22 tools that any MCP-compatible client (Claude Desktop, Claude Code, custom agents) can call:

Macro economic events

Earnings

Markets

Discovery & help (read-only, no API key required)

Account (webhooks, API keys, billing)

Write tools & consent model

Mutating tools follow an explicit human-in-the-loop pattern:

• `confirm: true` required. Called without it, a mutating tool makes no API call and returns a preview of exactly what would happen, so the agent can get the user's approval first.
• Billing mandate. create_checkout_session never charges anything — it returns a Stripe-hosted checkout URL that a human must open in a browser and complete. No card data ever passes through the tool or QuantGist's API. The plan upgrades automatically after payment.
• Once-only secrets. New API keys and webhook signing secrets are returned exactly once, with a warning to store them in an env var or secrets manager — never in committed files.
• Server-side enforcement stands. Plan gates (webhooks require Pro) and key scopes are enforced by the QuantGist API itself; the tools surface actionable hints on 403s rather than bypassing anything.

Requirements

• Python 3.10+ (for the local/stdio install — not needed for the hosted server)
• A QuantGist API key — get one at quantgist.com (free tier: 100 calls/day)

Connect to the hosted server (no install)

The MCP server is hosted over HTTP at `https://api.quantgist.com/mcp` — no install, no Python. Any client that supports the streamable-HTTP transport can connect by sending your QuantGist key in an X-API-Key header (multi-tenant: billed to your own quota).

Claude Code, in one command:

claude mcp add --transport http quantgist https://api.quantgist.com/mcp \

--header "X-API-Key: qg_live_YOUR_KEY"

Any streamable-HTTP MCP client:

{

"mcpServers": { "quantgist": { "type": "streamable-http", "url": "https://api.quantgist.com/mcp", "headers": { "X-API-Key": "qg_live_YOUR_KEY" } } } }

Connectors that only accept a URL (e.g. ChatGPT): if you can't set a custom header, put the key in the URL instead — https://api.quantgist.com/mcp?apiKey=qg_live_YOUR_KEY (also accepts Authorization: Bearer ). The header is preferred where possible, since a key in the URL can be recorded in proxy/server logs.

Prefer to run it yourself? Install locally (below) or self-host the HTTP server — see DEPLOY.md.

Installation

Option A — install from the package (recommended)

pip install quantgist-mcp

or with uv:

uv pip install quantgist-mcp

Option B — install from source (development)

git clone https://github.com/QuantGist-Technologies/QuantGist_MCP

cd QuantGist_MCP uv sync # installs all dependencies into a venv uv run quantgist-mcp # start the server

Claude Desktop configuration

Locate your Claude Desktop config file:

Add the quantgist server block (see claude_desktop_config_example.json):

{

"mcpServers": { "quantgist": { "command": "quantgist-mcp", "env": { "QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE" } } } }

Restart Claude Desktop after saving. The tools will appear in the tool list.

Using uv run instead of a global install

If you prefer not to install globally, point Claude Desktop at uv run:

{

"mcpServers": { "quantgist": { "command": "uv", "args": ["run", "--directory", "/absolute/path/to/Quangist_MCP", "quantgist-mcp"], "env": { "QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE" } } } }

Claude Code configuration

Add to .claude/mcp_settings.json in your project (or the global ~/.claude/mcp_settings.json):

{

"mcpServers": { "quantgist": { "command": "quantgist-mcp", "env": { "QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE" } } } }

Self-hosting (HTTP transport)

Besides the stdio transport above, the server can run as a hosted HTTP service via the quantgist-mcp-http entry point (GET /health, MCP at /mcp). It accepts a per-request X-API-Key header (multi-tenant) or a server-side QUANTGIST_API_KEY env var.

docker build -t quantgist-mcp .

docker run -p 8000:8000 -e QUANTGIST_API_KEY=qg_live_YOUR_KEY quantgist-mcp curl http://localhost:8000/health

See DEPLOY.md for Docker, Docker Compose, and Coolify deployment.

Tool reference

get_upcoming_events

Returns events in the next N hours.

get_events_range

Returns events in a date range.

get_economic_calendar

Returns the day's macro calendar grouped by release time. This tool calls GET /v1/calendar?envelope=true, not the broad /events feed, so general financial-news headlines are not mixed into scheduled macro releases.

The structured output preserves the backend envelope:

• events / count / returned_count
• total_count
• coverage
• warnings
• truncated
• schema_version

If the backend response is partial, stale, truncated by the MCP safety cap, or missing the required calendar envelope, the tool surfaces that in warnings and does not fall back to /events.

get_event_detail

Returns full detail for one event.

get_earnings_upcoming

Returns the next upcoming earnings reports across all tickers, ordered by report date.

get_earnings_for_ticker

Returns earnings history for a single ticker (EPS estimate vs actual, revenue, beat/miss, EDGAR links).

get_earnings_summary

Returns beat / miss / in-line counts and overall beat rate for a ticker.

get_earnings_surprises

Returns the largest EPS surprises across the market in the most recent reports.

get_earnings_season_summary

Returns the index-level summary of the current earnings season (total reports, overall beat rate, average EPS surprise, season label). No parameters.

get_markets_overview

Returns end-of-day quotes for major market indices and instruments (S&P 500, Nasdaq, Dow Jones, gold, oil, etc.). No parameters.

get_subscription

Returns the authenticated account's plan, status, and billing period. No parameters. Read-only.

list_webhooks

Lists the account's registered webhook endpoints. No parameters. Read-only; webhooks require the Pro plan.

create_webhook

Registers an HTTPS webhook endpoint (Pro plan). Confirm-gated: without confirm: true it returns a preview and makes no API call. The signing secret is returned once only.

delete_webhook

Permanently deletes a webhook endpoint and its delivery history. Confirm-gated and destructive.

| Parameter