quantgist-mcp

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

Tool	Description
get_upcoming_events	Events scheduled in the next N hours, filtered by impact
get_events_range	Events in a date range with optional country/symbol/impact filters
get_economic_calendar	Full day macro calendar from /calendar, grouped by time, with coverage/warnings metadata
get_event_detail	Full details for one event by ID (actual, forecast, previous, symbols)

Earnings

Tool	Description
get_earnings_upcoming	Next upcoming earnings reports across all tickers, with EPS/revenue estimates
get_earnings_for_ticker	Earnings history for one ticker (estimate vs actual, beat/miss, EDGAR links)
get_earnings_summary	Beat / miss / in-line counts and overall beat rate for a ticker
get_earnings_surprises	Largest EPS surprises across the market in the latest reports
get_earnings_season_summary	Index-level summary of the current earnings season

Markets

Tool	Description
get_markets_overview	End-of-day quotes for major indices and instruments (S&P 500, Nasdaq, gold, oil…)

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

Tool	Description
get_pricing	Plans, prices, and feature gates (free → enterprise) + the Bot Usage Add-On
get_limits	Per-plan caps: request quotas, history window, data delay, WS, watchlists, rate limiting
recommend_endpoint	Map a natural-language use case to the best REST endpoint + MCP tool
get_status	Check API reachability and link the public status page
estimate_usage_cost	Estimate which plan fits a request volume + overage / Bot Usage Add-On notes

Account (webhooks, API keys, billing)

Tool	Description
get_subscription	Current plan, status, and billing period (read-only)
list_webhooks	Registered webhook endpoints (read-only; Pro plan)
create_webhook	Register an HTTPS webhook endpoint — confirm-gated; signing secret shown once
delete_webhook	Permanently delete a webhook endpoint — confirm-gated, destructive
test_webhook	Send a signed synthetic test delivery to verify your consumer
create_api_key	Create a (optionally scoped) API key — confirm-gated; key shown once
create_checkout_session	Create a Stripe Checkout session for a plan upgrade — confirm-gated; never charges

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:

Platform	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

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.

Parameter	Type	Default	Description
hours	integer (1–168)	24	Look-ahead window in hours
impact	high | medium | low | all	high	Impact filter

get_events_range

Returns events in a date range.

Parameter	Type	Required	Description
from_date	ISO string	Yes	Start date/datetime
to_date	ISO string	Yes	End date/datetime
country	string	No	2-letter country code (e.g. "US")
impact	enum	No	high | medium | low | all
symbol	string	No	Trading symbol (e.g. "XAUUSD")

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.

Parameter	Type	Default	Description
date	ISO date	today (UTC)	Date to fetch
impact	enum	high	Impact filter

get_event_detail

Returns full detail for one event.

Parameter	Type	Required	Description
event_id	string	Yes	Event ID from any other tool

get_earnings_upcoming

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

Parameter	Type	Default	Description
limit	integer (1–100)	20	Number of upcoming reports to return

get_earnings_for_ticker

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

Parameter	Type	Default	Description
ticker	string	required	Stock ticker, e.g. "AAPL"
limit	integer (1–50)	10	Number of historical reports to return

get_earnings_summary

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

Parameter	Type	Required	Description
ticker	string	Yes	Stock ticker, e.g. "AAPL"

get_earnings_surprises

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

Parameter	Type	Default	Description
limit	integer (1–50)	20	Number of top surprises to return

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.

Parameter	Type	Default	Description
url	string (required)	—	HTTPS URL that will receive event POSTs
events	string[]	["*"]	Event types: economic_release, earnings, earnings.scheduled, earnings.confirmed, earnings.reported, earnings.surprise, news.radar.breaking, or *
impact_filter	string[]	—	Only deliver events with these impact levels, e.g. ["high"]
confirm	boolean	false	Must be true to actually create

delete_webhook

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

Parameter	Type	Default	Description
webhook_id	string (required)	—	Endpoint ID from list_webhooks
confirm	boolean	false	Must be true to actually delete

test_webhook

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

Parameter	Type	Default	Description
webhook_id	string (required)	—	Endpoint ID from list_webhooks

create_api_key

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

Parameter	Type	Default	Description
name	string	"Agent key"	Human-readable label
environment	live | test	live	Production data vs sandbox
scopes	string[]	["*"]	Prefer least privilege: events:read, calendar:read, webhooks:manage, usage:read, watchlists:manage
confirm	boolean	false	Must be true to actually create

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.

Parameter	Type	Default	Description
plan	starter | pro | team (required)	—	Target plan
confirm	boolean	false	Must be true, and only after the user explicitly approved the upgrade

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

Variable	Required	Description
QUANTGIST_API_KEY	Yes	Your QuantGist API key (qg_live_... or qg_test_...)

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