{
  "markdown": "# QuantGist MCP Server\n\n<!-- mcp-name: io.github.QuantGist-Technologies/quantgist-mcp -->\n\n[![smithery badge](https://smithery.ai/badge/quantgist/quantgist-mcp)](https://smithery.ai/servers/quantgist/quantgist-mcp)\n\nExposes [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.\n\n## What it does\n\nThe server registers 22 tools that any MCP-compatible client (Claude Desktop, Claude Code, custom agents) can call:\n\n**Macro economic events**\n\n| Tool | Description |\n|------|-------------|\n| `get_upcoming_events` | Events scheduled in the next N hours, filtered by impact |\n| `get_events_range` | Events in a date range with optional country/symbol/impact filters |\n| `get_economic_calendar` | Full day macro calendar from `/calendar`, grouped by time, with coverage/warnings metadata |\n| `get_event_detail` | Full details for one event by ID (actual, forecast, previous, symbols) |\n\n**Earnings**\n\n| Tool | Description |\n|------|-------------|\n| `get_earnings_upcoming` | Next upcoming earnings reports across all tickers, with EPS/revenue estimates |\n| `get_earnings_for_ticker` | Earnings history for one ticker (estimate vs actual, beat/miss, EDGAR links) |\n| `get_earnings_summary` | Beat / miss / in-line counts and overall beat rate for a ticker |\n| `get_earnings_surprises` | Largest EPS surprises across the market in the latest reports |\n| `get_earnings_season_summary` | Index-level summary of the current earnings season |\n\n**Markets**\n\n| Tool | Description |\n|------|-------------|\n| `get_markets_overview` | End-of-day quotes for major indices and instruments (S&P 500, Nasdaq, gold, oil…) |\n\n**Discovery & help** (read-only, no API key required)\n\n| Tool | Description |\n|------|-------------|\n| `get_pricing` | Plans, prices, and feature gates (free → enterprise) + the Bot Usage Add-On |\n| `get_limits` | Per-plan caps: request quotas, history window, data delay, WS, watchlists, rate limiting |\n| `recommend_endpoint` | Map a natural-language use case to the best REST endpoint + MCP tool |\n| `get_status` | Check API reachability and link the public status page |\n| `estimate_usage_cost` | Estimate which plan fits a request volume + overage / Bot Usage Add-On notes |\n\n**Account** (webhooks, API keys, billing)\n\n| Tool | Description |\n|------|-------------|\n| `get_subscription` | Current plan, status, and billing period (read-only) |\n| `list_webhooks` | Registered webhook endpoints (read-only; Pro plan) |\n| `create_webhook` | Register an HTTPS webhook endpoint — confirm-gated; signing secret shown once |\n| `delete_webhook` | Permanently delete a webhook endpoint — confirm-gated, destructive |\n| `test_webhook` | Send a signed synthetic test delivery to verify your consumer |\n| `create_api_key` | Create a (optionally scoped) API key — confirm-gated; key shown once |\n| `create_checkout_session` | Create a Stripe Checkout session for a plan upgrade — confirm-gated; **never charges** |\n\n### Write tools & consent model\n\nMutating tools follow an explicit human-in-the-loop pattern:\n\n- **`confirm: true` required.** Called without it, a mutating tool makes **no API call** and\n  returns a preview of exactly what would happen, so the agent can get the user's approval first.\n- **Billing mandate.** `create_checkout_session` never charges anything — it returns a\n  Stripe-hosted checkout URL that a human must open in a browser and complete. No card data ever\n  passes through the tool or QuantGist's API. The plan upgrades automatically after payment.\n- **Once-only secrets.** New API keys and webhook signing secrets are returned exactly once, with\n  a warning to store them in an env var or secrets manager — never in committed files.\n- **Server-side enforcement stands.** Plan gates (webhooks require Pro) and key scopes are\n  enforced by the QuantGist API itself; the tools surface actionable hints on 403s rather than\n  bypassing anything.\n\n## Requirements\n\n- Python 3.10+ (for the local/stdio install — not needed for the hosted server)\n- A QuantGist API key — get one at [quantgist.com](https://quantgist.com) (free tier: 100 calls/day)\n\n## Connect to the hosted server (no install)\n\nThe MCP server is hosted over HTTP at **`https://api.quantgist.com/mcp`** — no install, no\nPython. Any client that supports the streamable-HTTP transport can connect by sending your\nQuantGist key in an `X-API-Key` header (multi-tenant: billed to your own quota).\n\nClaude Code, in one command:\n\n```bash\nclaude mcp add --transport http quantgist https://api.quantgist.com/mcp \\\n  --header \"X-API-Key: qg_live_YOUR_KEY\"\n```\n\nAny streamable-HTTP MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"quantgist\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://api.quantgist.com/mcp\",\n      \"headers\": { \"X-API-Key\": \"qg_live_YOUR_KEY\" }\n    }\n  }\n}\n```\n\n**Connectors that only accept a URL (e.g. ChatGPT):** if you can't set a custom header, put the\nkey in the URL instead — `https://api.quantgist.com/mcp?apiKey=qg_live_YOUR_KEY` (also accepts\n`Authorization: Bearer <key>`). The header is preferred where possible, since a key in the URL can\nbe recorded in proxy/server logs.\n\nPrefer to run it yourself? Install locally (below) or self-host the HTTP server — see [DEPLOY.md](DEPLOY.md).\n\n## Installation\n\n### Option A — install from the package (recommended)\n\n```bash\npip install quantgist-mcp\n# or with uv:\nuv pip install quantgist-mcp\n```\n\n### Option B — install from source (development)\n\n```bash\ngit clone https://github.com/QuantGist-Technologies/QuantGist_MCP\ncd QuantGist_MCP\nuv sync          # installs all dependencies into a venv\nuv run quantgist-mcp   # start the server\n```\n\n## Claude Desktop configuration\n\nLocate your Claude Desktop config file:\n\n| Platform | Path |\n|----------|------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\nAdd the `quantgist` server block (see `claude_desktop_config_example.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"quantgist\": {\n      \"command\": \"quantgist-mcp\",\n      \"env\": {\n        \"QUANTGIST_API_KEY\": \"qg_live_YOUR_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving. The tools will appear in the tool list.\n\n### Using `uv run` instead of a global install\n\nIf you prefer not to install globally, point Claude Desktop at `uv run`:\n\n```json\n{\n  \"mcpServers\": {\n    \"quantgist\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/absolute/path/to/Quangist_MCP\", \"quantgist-mcp\"],\n      \"env\": {\n        \"QUANTGIST_API_KEY\": \"qg_live_YOUR_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\n## Claude Code configuration\n\nAdd to `.claude/mcp_settings.json` in your project (or the global `~/.claude/mcp_settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"quantgist\": {\n      \"command\": \"quantgist-mcp\",\n      \"env\": {\n        \"QUANTGIST_API_KEY\": \"qg_live_YOUR_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\n## Self-hosting (HTTP transport)\n\nBesides the stdio transport above, the server can run as a hosted HTTP service via the\n`quantgist-mcp-http` entry point (`GET /health`, MCP at `/mcp`). It accepts a per-request\n`X-API-Key` header (multi-tenant) or a server-side `QUANTGIST_API_KEY` env var.\n\n```bash\ndocker build -t quantgist-mcp .\ndocker run -p 8000:8000 -e QUANTGIST_API_KEY=qg_live_YOUR_KEY quantgist-mcp\ncurl http://localhost:8000/health\n```\n\nSee [DEPLOY.md](DEPLOY.md) for Docker, Docker Compose, and Coolify deployment.\n\n## Tool reference\n\n### `get_upcoming_events`\n\nReturns events in the next N hours.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `hours` | integer (1–168) | 24 | Look-ahead window in hours |\n| `impact` | high \\| medium \\| low \\| all | high | Impact filter |\n\n### `get_events_range`\n\nReturns events in a date range.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `from_date` | ISO string | Yes | Start date/datetime |\n| `to_date` | ISO string | Yes | End date/datetime |\n| `country` | string | No | 2-letter country code (e.g. \"US\") |\n| `impact` | enum | No | high \\| medium \\| low \\| all |\n| `symbol` | string | No | Trading symbol (e.g. \"XAUUSD\") |\n\n### `get_economic_calendar`\n\nReturns the day's macro calendar grouped by release time. This tool calls\n`GET /v1/calendar?envelope=true`, not the broad `/events` feed, so general\nfinancial-news headlines are not mixed into scheduled macro releases.\n\nThe structured output preserves the backend envelope:\n\n- `events` / `count` / `returned_count`\n- `total_count`\n- `coverage`\n- `warnings`\n- `truncated`\n- `schema_version`\n\nIf the backend response is partial, stale, truncated by the MCP safety cap, or\nmissing the required calendar envelope, the tool surfaces that in `warnings` and\ndoes not fall back to `/events`.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `date` | ISO date | today (UTC) | Date to fetch |\n| `impact` | enum | high | Impact filter |\n\n### `get_event_detail`\n\nReturns full detail for one event.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `event_id` | string | Yes | Event ID from any other tool |\n\n### `get_earnings_upcoming`\n\nReturns the next upcoming earnings reports across all tickers, ordered by report date.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `limit` | integer (1–100) | 20 | Number of upcoming reports to return |\n\n### `get_earnings_for_ticker`\n\nReturns earnings history for a single ticker (EPS estimate vs actual, revenue, beat/miss, EDGAR links).\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `ticker` | string | required | Stock ticker, e.g. \"AAPL\" |\n| `limit` | integer (1–50) | 10 | Number of historical reports to return |\n\n### `get_earnings_summary`\n\nReturns beat / miss / in-line counts and overall beat rate for a ticker.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `ticker` | string | Yes | Stock ticker, e.g. \"AAPL\" |\n\n### `get_earnings_surprises`\n\nReturns the largest EPS surprises across the market in the most recent reports.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `limit` | integer (1–50) | 20 | Number of top surprises to return |\n\n### `get_earnings_season_summary`\n\nReturns the index-level summary of the current earnings season (total reports, overall beat rate, average EPS surprise, season label). No parameters.\n\n### `get_markets_overview`\n\nReturns end-of-day quotes for major market indices and instruments (S&P 500, Nasdaq, Dow Jones, gold, oil, etc.). No parameters.\n\n### `get_subscription`\n\nReturns the authenticated account's plan, status, and billing period. No parameters. Read-only.\n\n### `list_webhooks`\n\nLists the account's registered webhook endpoints. No parameters. Read-only; webhooks require the Pro plan.\n\n### `create_webhook`\n\nRegisters 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.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `url` | string (required) | — | HTTPS URL that will receive event POSTs |\n| `events` | string[] | `[\"*\"]` | Event types: `economic_release`, `earnings`, `earnings.scheduled`, `earnings.confirmed`, `earnings.reported`, `earnings.surprise`, `news.radar.breaking`, or `*` |\n| `impact_filter` | string[] | — | Only deliver events with these impact levels, e.g. `[\"high\"]` |\n| `confirm` | boolean | `false` | Must be `true` to actually create |\n\n### `delete_webhook`\n\nPermanently deletes a webhook endpoint and its delivery history. Confirm-gated and destructive.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `webhook_id` | string (required) | — | Endpoint ID from `list_webhooks` |\n| `confirm` | boolean | `false` | Must be `true` to actually delete |\n\n### `test_webhook`\n\nSends a signed synthetic test event to a webhook endpoint so you can verify reachability and `X-QuantGist-Signature` verification.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `webhook_id` | string (required) | — | Endpoint ID from `list_webhooks` |\n\n### `create_api_key`\n\nCreates a new API key, optionally scoped. Confirm-gated. The full key is returned once only — store it securely.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `name` | string | `\"Agent key\"` | Human-readable label |\n| `environment` | `live` \\| `test` | `live` | Production data vs sandbox |\n| `scopes` | string[] | `[\"*\"]` | Prefer least privilege: `events:read`, `calendar:read`, `webhooks:manage`, `usage:read`, `watchlists:manage` |\n| `confirm` | boolean | `false` | Must be `true` to actually create |\n\n### `create_checkout_session`\n\nCreates a Stripe Checkout session for a plan upgrade. **Never charges** — returns a Stripe-hosted checkout URL a human must open and complete. Confirm-gated.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `plan` | `starter` \\| `pro` \\| `team` (required) | — | Target plan |\n| `confirm` | boolean | `false` | Must be `true`, and only after the user explicitly approved the upgrade |\n\n## Example prompts\n\nThese prompts work out of the box once the server is connected:\n\n- \"What high-impact events are in the next 4 hours?\"\n- \"Show me today's full economic calendar\"\n- \"Show me this week's high-impact USD events\"\n- \"What macro events affect EURUSD this Friday?\"\n- \"Get me details on event ID abc123\"\n- \"Which companies report earnings soon?\"\n- \"Show me AAPL's earnings beat rate\"\n- \"What were the biggest EPS surprises this season?\"\n- \"Give me a quick market overview\"\n- \"What plan am I on?\"\n- \"Set up a webhook to https://my-bot.example.com/hooks for high-impact USD events\"\n- \"Create a read-only test API key for my backtester\"\n- \"I want to upgrade to Pro\" *(the agent hands you a Stripe checkout link — payment always stays with you)*\n\n## Environment variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `QUANTGIST_API_KEY` | Yes | Your QuantGist API key (`qg_live_...` or `qg_test_...`) |\n\n## Development\n\n```bash\nuv sync\nuv run quantgist-mcp          # run the MCP server\nuv run pytest                 # run tests (if present)\nuv run ruff check src/        # lint\nuv run ruff format src/       # format\n```\n\n## API rate limits\n\nThe 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.\n\n## License\n\nMIT\n",
  "bytes": 14985,
  "sha": "52347a4db520c50a9ead8e0f8bf811e3fe3b124a0cd6292b646e1be6dc3ecb28",
  "repo_slug": "quantgist-technologies/quantgist_mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_quantgist_technologies_quantgi_e4ee61b1/readme"
}