StatBridge

Official statistics, ready to use. Verified access to ISTAT, Eurostat, OECD and ECB through a hosted REST API, with the local MCP toolkit included in this repo.

statbridge.net

---

What's in this repo

Directory	What it does
sdk/	Python SDK — thin API client (pip install statbridge), just httpx
statbridge/	Core library — SDMX client, topic registry, 4 verified source adapters
mcp_server/	FastMCP server — 9 tools: search, browse, describe, coverage, get data, chart, map
api/	FastAPI service — runs on the VPS behind Cloudflare Tunnel
web/	Next.js 14 app — marketing site, dashboard, docs, auth
agents/	Shared repo-local agent instructions
db/	Postgres schema for accounts, API keys, and usage events
docs/	API and MCP reference docs
CHART_GUIDELINES.md	StatBridge standards for choosing and formatting charts
CHART_RENDERER_CHECKLIST.md	Short operational checklist used by the chart tool
tests/	Unit tests (98 passing)

---

Product

Plan	Price	Volume
Starter	€9/mo	500 req/mo
Pro	€29/mo	5,000 req/mo

Every plan gets the same API, same response format, same source metadata. The hosted product is the REST API. The local MCP server and Python toolkit remain available in this repo for advanced workflows.

---

Production stack

• Compute: Ubuntu VPS (statbridge-vps)
• Edge / TLS: Cloudflare Tunnel (no Nginx needed)
• Web app: Next.js 14 via next start on port 3000
• API app: FastAPI via Uvicorn on port 8000
• Database: Local PostgreSQL
• Auth: NextAuth (Google OAuth)
• Billing: Stripe
• Object storage: Cloudflare R2 (optional, for exports/media)
• DNS: Cloudflare

User → Cloudflare Tunnel
         ├─ statbridge.net      → Next.js (port 3000)
         ├─ api.statbridge.net  → FastAPI (port 8000)
         └─ catch-all           → 404

Both services run as systemd units. See DEPLOYMENT.md for the full setup.

---

Verified sources

Source	Status	Coverage
ISTAT	Live	Italy — regional labour, agriculture, daily life
Eurostat	Live	EU-wide economic + social
OECD	Live	International
ECB	Live	Eurozone — rates, monetary
IMF, ILO, BIS, World Bank	Planned	—

25 live topics today.

---

Python SDK

The recommended way to use StatBridge from Python. One dependency (httpx), no heavy SDMX stack.

pip install statbridge

from statbridge_sdk import StatBridge

sb = StatBridge()  # reads STATBRIDGE_API_KEY from env

sb.search("gdp")
sb.get("unemployment_rate", REF_AREA="IT")
sb.topics()
sb.dimensions("inflation")
sb.health()

Core library (advanced)

For local SDMX access without the hosted API (used internally by the MCP server):

pip install -e ".[dev]"

import statbridge

df = statbridge.get("unemployment_rate")
statbridge.search("gdp")
statbridge.subject_areas()
statbridge.browse(subject_area="labour")
statbridge.describe("inflation")
statbridge.coverage()

Available topics

unemployment_rate · employment_rate · gdp_growth · inflation · population · life_expectancy · government_debt · trade_balance · interest_rates · house_prices · education_expenditure · co2_emissions · gini_coefficient · poverty_rate · neet_rate · housing_cost_overburden · energy_import_dependency · labour_productivity_growth · tourism_nights_per_capita · health_expenditure · tax_revenue · average_annual_wages · median_household_income · foreign_born_population

---

MCP server

pip install mcp-server-statbridge

Add to Claude Desktop, VS Code, Cursor, or any MCP client:

{
  "mcpServers": {
    "statbridge": {
      "command": "uvx",
      "args": ["mcp-server-statbridge"]
    }
  }
}

Tools: list_sources · list_subject_areas · search_data · browse_topics · describe_topic · coverage_report · get_data · create_chart · create_map

---

Local development

Next.js (web/)

cd web
cp .env.example .env.local   # fill in keys
npm install && npm run dev

FastAPI (api/)

cd api
cp .env.example .env
pip install -r requirements.txt
uvicorn main:app --reload

---

Tests

# Unit (no network)
python -m pytest tests/unit/ -v

# Integration (requires network)
python -m pytest tests/integration/ -m integration -v

# Coverage report
python -m statbridge.verification

---

Roadmap

• IMF, ILO, World Bank, BIS source adapters
• R2-backed chart export endpoint (/v1/chart → PNG URL)
• R2-backed map export endpoint (/v1/map → PNG URL)
• Team plan (shared usage pool, multiple seats)