io.github.ykshah1309/global-sentinel-mcp

global-sentinel-mcp

An async MCP server unifying prediction markets, global news events, aviation state, and internet-infrastructure telemetry into one alternative-data layer for macro and financial analysis.

Status: Beta — ready for production use; public API may still shift before 1.0.

Why this exists

Alternative data — prediction-market odds, real-time geopolitical event streams, live aviation transponder data, and internet-infrastructure telemetry — is increasingly central to macro and financial analysis. Each source has its own API shape, authentication model, and update cadence, making it tedious to wire them together for every new project.

global-sentinel-mcp closes that gap by wrapping four public data feeds behind a single Model Context Protocol (MCP) interface. An LLM agent can ask probability, event, aviation-state, and internet-telemetry questions in one place, without knowing the upstream API details. It also exposes a composite macro alert tool that fuses news events and outage annotations into one convergence signal with a human-readable explanation.

The server is fully async (httpx.AsyncClient with retry transport), returns typed Pydantic v2 models for every response and error, ships a TTL cache per source to stay within upstream rate limits, and installs in one command over stdio — no web server required.

Available Tools

Quickstart

1. Install

uvx global-sentinel-mcp

Or install from PyPI:

pip install global-sentinel-mcp

2. Set environment variables (all optional — unset tools degrade gracefully)

# OpenSky — OAuth2 preferred (post-2025 migration), Basic Auth for legacy accounts.
export OPENSKY_CLIENT_ID="your_opensky_client_id"
export OPENSKY_CLIENT_SECRET="your_opensky_client_secret"
# Cloudflare Radar — required for BGP and outage tools.
export CLOUDFLARE_API_TOKEN="your_cf_token"
# Optional.
export LOG_LEVEL="INFO"

3. Run

global-sentinel-mcp

The server speaks MCP JSON-RPC over stdio.

Local development

git clone https://github.com/ykshah1309/global-sentinel-mcp
cd global-sentinel-mcp
uv sync --dev
uv run global-sentinel-mcp        # run the server
uv run pytest tests/ -v           # run the test suite
uv run ruff check src/ tests/     # lint
uv run mypy src/                  # type-check

Claude Desktop configuration

Add to claude_desktop_config.json (see claude_desktop_config.example.json):

{
  "mcpServers": {
    "global-sentinel": {
      "command": "uvx",
      "args": ["global-sentinel-mcp"],
      "env": {
        "OPENSKY_CLIENT_ID": "your_opensky_client_id",
        "OPENSKY_CLIENT_SECRET": "your_opensky_client_secret",
        "CLOUDFLARE_API_TOKEN": "your_cf_token"
      }
    }
  }
}

Cursor configuration

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "global-sentinel": {
      "command": "uvx",
      "args": ["global-sentinel-mcp"],
      "env": {
        "OPENSKY_CLIENT_ID": "your_opensky_client_id",
        "OPENSKY_CLIENT_SECRET": "your_opensky_client_secret",
        "CLOUDFLARE_API_TOKEN": "your_cf_token"
      }
    }
  }
}

Environment Variables

Polymarket and GDELT tools require no authentication. Anonymous OpenSky is allowed but heavily rate-limited.

Data Sources

Polymarket (Gamma API)

Crowd-sourced prediction market data. Token prices reflect the crowd's estimated probability of future events. No API key required. Events expose outcomes and outcomePrices as JSON-encoded strings — the client parses the "Yes" leg and returns it as probability_pct. Docs

GDELT 2.0

The world's largest open-access global news event database, updated every 15 minutes. Events are coded with actors, event types, Goldstein conflict/cooperation scores, and geographic coordinates. Per publish cycle the server downloads and parses the 5 MB export zip exactly once, then answers all country queries from an in-memory DataFrame cache. Docs

OpenSky Network

Public ADS-B flight tracking from a global network of volunteer receivers. Returns real-time position, altitude, velocity, and on-ground status for any aircraft with a Mode S transponder. Post-2025 the service moved to OAuth2 client-credentials; this server handles token refresh automatically and falls back to Basic Auth (legacy) or anonymous if credentials are absent. Docs

Cloudflare Radar

Internet-infrastructure telemetry from Cloudflare's global network. Covers BGP routing anomalies (/bgp/hijacks/events, /bgp/leaks/events) and regional outage annotations (/annotations/outages, formerly "traffic anomalies", renamed by Cloudflare in 2024). Requires a free Cloudflare API token. Docs

Contributing

See CONTRIBUTING.md for setup instructions, branch naming conventions, testing requirements, and code style guidelines.

License

MIT — Copyright (c) 2026 ykshah1309