QuantGist MCP Server

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 ten tools that any MCP-compatible client (Claude Desktop, Claude Code, custom agents) can call:

Macro economic events

Earnings

Markets

Requirements

• Python 3.10+
• A QuantGist API key — get one at quantgist.com (free tier: 100 calls/day)

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