marc-shade/world-intel-mcp

TL;DR

World‑Intelligence MCP Server is a Python‑based data‑collection and analysis platform that gathers free public‑API data from dozens of domains (finance, geopolitics, climate, military, cyber, health, etc.). It stores the results in a SQLite cache and a Qdrant vector store, exposing them via the Model Context Protocol (MCP) so AI agents (e.g., Claude, Cursor) can query the world in natural language. A live dashboard, CLI, and PDF/HTML report generator let humans explore the same data.

---

What it does (in plain language)

Feature	What you get
Broad‑scope data collection	139 “tools” pull data from 30+ domains – stock markets, central‑bank rates, earthquake feeds, military flight trackers, cyber‑threat lists, refugee flows, etc. All sources are free public APIs, no paid subscriptions.
MCP‑compatible server	The program runs as a standard‑input/output service that follows the Model Context Protocol, letting LLM‑based agents ask questions like “show recent cyber threats targeting hospitals” and receive structured results.
Semantic search	Every fetched record is embedded with the BAAI bge‑small‑en‑v1.5 model and stored in Qdrant. Users can ask natural‑language queries and get similarity‑based matches across the whole historic dataset.
Live ops‑center dashboard	A Streamlit UI (leaflet map, layer toggles, real‑time SSE feeds) visualises earthquakes, military activity, conflict events, infrastructure status, and user‑defined geofences.
Command‑line interface	intel <domain> commands give quick one‑liners (e.g., intel markets, intel earthquakes --min-mag 5).
Automated reporting	intel report builds a multi‑section PDF or HTML brief that summarises selected domains, complete with citations.
Geofence alerts	Define circles/polygons/corridors; the system watches for new events entering or leaving those areas and produces a brief with escalation scores.
Cross‑domain analytics	Tools combine signals (e.g., instability index, risk scores, signal convergence) to produce higher‑level intelligence such as a global risk posture or country dossiers.

---

Who might use it

Audience	Why it matters
AI agents / autonomous analysts	Provides a single, MCP‑compatible endpoint for agents to retrieve up‑to‑date world facts without building dozens of API wrappers.
Strategic analysts / risk teams	Gives a ready‑made, citation‑backed daily brief and the ability to run custom semantic searches across many domains.
Developers building bots	The CLI and Python library let you embed any of the 139 tools in your own workflow or product.
Researchers	All raw data is cached locally (SQLite) and vectorised, making it easy to experiment with multi‑modal analysis.

---

How it works (high‑level architecture)

1. Collector daemon – runs every 5 minutes, asynchronously fetches every source module (sources/*.py) using httpx. Each source has its own circuit‑breaker that pauses after 3 consecutive failures. |
2. Cache – SQLite (WAL mode) stores the latest JSON payloads with a TTL; stale data can still be returned if fresh data is unavailable. |
3. Vector store – New records are embedded with FastEmbed (384‑dim BGE model) and pushed to Qdrant in a background queue, enabling semantic similarity queries. |
4. MCP server – server.py reads commands from stdin/stdout, maps them to the appropriate tool, and returns JSON results that conform to the Model Context Protocol. |
5. Dashboard / CLI – Thin wrappers (dashboard.py, cli.py) call the same library functions, presenting data via Streamlit or Click. |

---

Quick start checklist

# 1. Clone & install (editable mode)
git clone https://github.com/marc-shade/world-intel-mcp.git
cd world-intel-mcp
pip install -e .            # core
pip install -e ".[dashboard]"  # optional UI
pip install -e ".[vector]"     # Qdrant + embeddings

# 2. Run the MCP server (or the collector daemon in another terminal)
world-intel-mcp               # stdio server for LLMs
# optional: start background collector
collector.py &

# 3. Try a CLI command
intel markets                # shows major index quotes

# 4. Open the dashboard (default port 8501)
intel-dashboard

---

Limitations & things to watch

• Reliance on free APIs – rate limits and occasional outages are handled by circuit‑breakers, but data freshness can vary. |
• Local resource needs – Qdrant + SQLite can grow large (many millions of records) if you run the collector continuously. |
• Semantic quality – The BGE‑small embedding model is fast but not state‑of‑the‑art for every domain; search relevance may need tuning. |
• No paid‑data sources – If you need proprietary market depth or classified intel, this platform won’t provide it.

---

Bottom line

World‑Intelligence MCP is a real, open‑source intelligence aggregation engine aimed at giving LLM‑based agents (and human analysts) a single, searchable, citation‑rich view of the world using only publicly available data. It bundles data collection, caching, vector search, a dashboard, and reporting into a cohesive Python package.