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 <key>). 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.

test_webhook

Sends a signed synthetic test event to a webhook endpoint so you can verify reachability and X-QuantGist-Signature verification.

create_api_key

Creates a new API key, optionally scoped. Confirm-gated. The full key is returned once only — store it securely.

create_checkout_session

Creates a Stripe Checkout session for a plan upgrade. Never charges — returns a Stripe-hosted checkout URL a human must open and complete. Confirm-gated.

Example prompts

These prompts work out of the box once the server is connected:

• "What high-impact events are in the next 4 hours?"
• "Show me today's full economic calendar"
• "Show me this week's high-impact USD events"
• "What macro events affect EURUSD this Friday?"
• "Get me details on event ID abc123"
• "Which companies report earnings soon?"
• "Show me AAPL's earnings beat rate"
• "What were the biggest EPS surprises this season?"
• "Give me a quick market overview"
• "What plan am I on?"
• "Set up a webhook to https://my-bot.example.com/hooks for high-impact USD events"
• "Create a read-only test API key for my backtester"
• "I want to upgrade to Pro" (the agent hands you a Stripe checkout link — payment always stays with you)

Environment variables

Development

uv sync
uv run quantgist-mcp          # run the MCP server
uv run pytest                 # run tests (if present)
uv run ruff check src/        # lint
uv run ruff format src/       # format

API rate limits

The free tier allows 100 API calls/day with up to 365 days of event history. Each tool invocation makes 1–2 API calls. Upgrade at quantgist.com/pricing for higher limits.

License

MIT