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 fifteen 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)

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 calendar grouped by release time.

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.

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"

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