Content
# QuantGist MCP Server
<!-- mcp-name: io.github.QuantGist-Technologies/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
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available