# QuantGist MCP Server

<!-- mcp-name: io.github.QuantGist-Technologies/quantgist-mcp -->

[![smithery badge](https://smithery.ai/badge/quantgist/quantgist-mcp)](https://smithery.ai/servers/quantgist/quantgist-mcp)

Exposes [QuantGist](https://quantgist.com) 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](https://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:

```bash
claude mcp add --transport http quantgist https://api.quantgist.com/mcp \
  --header "X-API-Key: qg_live_YOUR_KEY"
```

Any streamable-HTTP MCP client:

```json
{
  "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](DEPLOY.md).

## Installation

### Option A — install from the package (recommended)

```bash
pip install quantgist-mcp
# or with uv:
uv pip install quantgist-mcp
```

### Option B — install from source (development)

```bash
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`):

```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`:

```json
{
  "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`):

```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.

```bash
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](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

```bash
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](https://quantgist.com/pricing) for higher limits.

## License

MIT