{
  "markdown": "# global-sentinel-mcp\n\n<!-- mcp-name: io.github.ykshah1309/global-sentinel-mcp -->\n\nAn async MCP server unifying **prediction markets, global news events, aviation state,\nand internet-infrastructure telemetry** into one alternative-data layer for macro and\nfinancial analysis.\n\n[![PyPI version](https://img.shields.io/pypi/v/global-sentinel-mcp)](https://pypi.org/project/global-sentinel-mcp/)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)\n[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![CI](https://github.com/ykshah1309/global-sentinel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ykshah1309/global-sentinel-mcp/actions/workflows/ci.yml)\n[![Publish](https://github.com/ykshah1309/global-sentinel-mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/ykshah1309/global-sentinel-mcp/actions/workflows/publish.yml)\n\nStatus: **Beta** — ready for production use; public API may still shift before 1.0.\n\n---\n\n## Why this exists\n\nAlternative data — prediction-market odds, real-time geopolitical event streams,\nlive aviation transponder data, and internet-infrastructure telemetry — is\nincreasingly central to macro and financial analysis. Each source has its own\nAPI shape, authentication model, and update cadence, making it tedious to wire\nthem together for every new project.\n\n`global-sentinel-mcp` closes that gap by wrapping four public data feeds behind\na single Model Context Protocol (MCP) interface. An LLM agent can ask\nprobability, event, aviation-state, and internet-telemetry questions in one\nplace, without knowing the upstream API details. It also exposes a composite\n**macro alert** tool that fuses news events and outage annotations into one\nconvergence signal with a human-readable explanation.\n\nThe server is fully async (`httpx.AsyncClient` with retry transport), returns\ntyped Pydantic v2 models for every response and error, ships a TTL cache per\nsource to stay within upstream rate limits, and installs in one command over\nstdio — no web server required.\n\n---\n\n## Available Tools\n\n| Tool | Data Source | What it returns |\n|---|---|---|\n| `get_prediction_odds` | Polymarket | Ranked event odds (probability %, volume, end date) for a query |\n| `get_prediction_event_by_id` | Polymarket | Odds for a specific event id or slug |\n| `lookup_aircraft_state` | OpenSky Network | Latest ADS-B state for a tail number (N-Number) or ICAO24 hex |\n| `convert_nnumber` | — (offline) | Pure-Python FAA N-Number ↔ ICAO24 conversion, no network needed |\n| `get_global_events` | GDELT 2.0 | High-impact events for a country, ranked by Goldstein scale |\n| `check_network_anomalies` | Cloudflare Radar | BGP hijacks + leaks and regional outage annotations |\n| `get_macro_alert` | GDELT + Cloudflare | Composite convergence signal with explanation string |\n\n---\n\n## Quickstart\n\n### 1. Install\n\n```bash\nuvx global-sentinel-mcp\n```\n\nOr install from PyPI:\n\n```bash\npip install global-sentinel-mcp\n```\n\n### 2. Set environment variables (all optional — unset tools degrade gracefully)\n\n```bash\n# OpenSky — OAuth2 preferred (post-2025 migration), Basic Auth for legacy accounts.\nexport OPENSKY_CLIENT_ID=\"your_opensky_client_id\"\nexport OPENSKY_CLIENT_SECRET=\"your_opensky_client_secret\"\n# Cloudflare Radar — required for BGP and outage tools.\nexport CLOUDFLARE_API_TOKEN=\"your_cf_token\"\n# Optional.\nexport LOG_LEVEL=\"INFO\"\n```\n\n### 3. Run\n\n```bash\nglobal-sentinel-mcp\n```\n\nThe server speaks MCP JSON-RPC over stdio.\n\n### Local development\n\n```bash\ngit clone https://github.com/ykshah1309/global-sentinel-mcp\ncd global-sentinel-mcp\nuv sync --dev\nuv run global-sentinel-mcp        # run the server\nuv run pytest tests/ -v           # run the test suite\nuv run ruff check src/ tests/     # lint\nuv run mypy src/                  # type-check\n```\n\n---\n\n## Claude Desktop configuration\n\nAdd to `claude_desktop_config.json` (see [claude_desktop_config.example.json](claude_desktop_config.example.json)):\n\n```json\n{\n  \"mcpServers\": {\n    \"global-sentinel\": {\n      \"command\": \"uvx\",\n      \"args\": [\"global-sentinel-mcp\"],\n      \"env\": {\n        \"OPENSKY_CLIENT_ID\": \"your_opensky_client_id\",\n        \"OPENSKY_CLIENT_SECRET\": \"your_opensky_client_secret\",\n        \"CLOUDFLARE_API_TOKEN\": \"your_cf_token\"\n      }\n    }\n  }\n}\n```\n\n## Cursor configuration\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"global-sentinel\": {\n      \"command\": \"uvx\",\n      \"args\": [\"global-sentinel-mcp\"],\n      \"env\": {\n        \"OPENSKY_CLIENT_ID\": \"your_opensky_client_id\",\n        \"OPENSKY_CLIENT_SECRET\": \"your_opensky_client_secret\",\n        \"CLOUDFLARE_API_TOKEN\": \"your_cf_token\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Environment Variables\n\n| Variable | Required for | Description |\n|---|---|---|\n| `OPENSKY_CLIENT_ID` | aviation (OAuth2, preferred) | OpenSky OAuth2 client id — [register free](https://opensky-network.org) |\n| `OPENSKY_CLIENT_SECRET` | aviation (OAuth2, preferred) | OpenSky OAuth2 client secret |\n| `OPENSKY_USERNAME` | aviation (legacy) | OpenSky Basic Auth username (pre-2025 accounts) |\n| `OPENSKY_PASSWORD` | aviation (legacy) | OpenSky Basic Auth password |\n| `CLOUDFLARE_API_TOKEN` | BGP + outages | Cloudflare API token with Radar read permissions |\n| `LOG_LEVEL` | — | Python log level (DEBUG / INFO / WARNING / ERROR). Default `INFO`. |\n\nPolymarket and GDELT tools require no authentication. Anonymous OpenSky is\nallowed but heavily rate-limited.\n\n---\n\n## Data Sources\n\n### Polymarket (Gamma API)\n\nCrowd-sourced prediction market data. Token prices reflect the crowd's\nestimated probability of future events. No API key required. Events expose\n`outcomes` and `outcomePrices` as JSON-encoded strings — the client parses the\n\"Yes\" leg and returns it as `probability_pct`.\n[Docs](https://docs.polymarket.com/)\n\n### GDELT 2.0\n\nThe world's largest open-access global news event database, updated every 15\nminutes. Events are coded with actors, event types, Goldstein\nconflict/cooperation scores, and geographic coordinates. Per publish cycle the\nserver downloads and parses the 5 MB export zip exactly once, then answers all\ncountry queries from an in-memory DataFrame cache.\n[Docs](https://www.gdeltproject.org/data.html)\n\n### OpenSky Network\n\nPublic ADS-B flight tracking from a global network of volunteer receivers.\nReturns real-time position, altitude, velocity, and on-ground status for any\naircraft with a Mode S transponder. Post-2025 the service moved to OAuth2\nclient-credentials; this server handles token refresh automatically and falls\nback to Basic Auth (legacy) or anonymous if credentials are absent.\n[Docs](https://openskynetwork.github.io/opensky-api/)\n\n### Cloudflare Radar\n\nInternet-infrastructure telemetry from Cloudflare's global network. Covers BGP\nrouting anomalies (`/bgp/hijacks/events`, `/bgp/leaks/events`) and regional\noutage annotations (`/annotations/outages`, formerly \"traffic anomalies\",\nrenamed by Cloudflare in 2024). Requires a free Cloudflare API token.\n[Docs](https://developers.cloudflare.com/radar/)\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, branch naming\nconventions, testing requirements, and code style guidelines.\n\n---\n\n## License\n\n[MIT](LICENSE) — Copyright (c) 2026 ykshah1309\n",
  "bytes": 7268,
  "sha": "69012c28ce6bdf8c25e6720ebcd09c06d0ccd0b8394d19b755025c185a37658c",
  "repo_slug": "ykshah1309/global-sentinel-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ykshah1309_global_sentinel_mcp_7fa1bc9f/readme"
}