mcp-statdb

mcp-statdb

Global macroeconomic statistics database MCP server, supporting China NBS and international institutions including World Bank, IMF, OECD, BIS, FRED. All data is fetched from real APIs — no mock data.

Data Sources

Source	Auth	Coverage
China NBS (data.stats.gov.cn)	None	Monthly / Quarterly / Yearly / Provincial domestic data
World Bank (api.worldbank.org)	None	200+ countries — GDP, CPI, trade, population, FDI, Gini, etc.
IMF DataMapper	None	WEO forecasts — GDP growth, inflation, government debt, current account
OECD SDMX	None	Member-country quarterly GDP, employment, leading indicators
BIS Statistics	None	Effective exchange rates, credit gaps, property prices, cross-border banking
FRED (Federal Reserve)	X-Fred-Api-Key request header	US rates, CNY/USD, oil, gold, S&P 500, M2
NBS Census	None	Population (2020), Economic (2018), Agriculture (2016) censuses
NBS Departments	None	Finance, Industry, Trade, Agriculture, PBoC monetary, Social Security, Housing, Energy

FRED API Key: Free registration at https://fred.stlouisfed.org/docs/api/api_key.html
Pass it as the X-Fred-Api-Key request header (HTTP mode) or set FRED_API_KEY env var (stdio mode).

---

Installation

npx (Recommended)

npx mcp-statdb

HTTP transport

npx mcp-statdb --port 12345

Install globally

npm install -g mcp-statdb
mcp-statdb

---

MCP Client Configuration

stdio mode (npx)

Supported clients: Claude Desktop, Cursor, Windsurf, Cherry Studio, Trae, Continue, and all MCP-compatible clients.

{
  "mcpServers": {
    "mcp-statdb": {
      "command": "npx",
      "args": ["mcp-statdb"]
    }
  }
}

With FRED support:

{
  "mcpServers": {
    "mcp-statdb": {
      "command": "npx",
      "args": ["mcp-statdb"],
      "env": {
        "FRED_API_KEY": "your_fred_api_key"
      }
    }
  }
}

HTTP mode (remote)

Supported clients: Trae, Cherry Studio, and other clients with HTTP transport support.

Free demo on ModelScope (no FRED):

{
  "mcpServers": {
    "mcp-statdb": {
      "url": "https://mcp.api-inference.modelscope.net/c2ca6ece4e9946/mcp"
    }
  }
}

HTTP mode with FRED:

{
  "mcpServers": {
    "mcp-statdb": {
      "url": "https://your-statdb-server/mcp",
      "headers": {
        "X-Fred-Api-Key": "your_fred_api_key"
      }
    }
  }
}

Free public demo by Alibaba Cloud ModelScope. No auth required. For production use, deploy your own instance.

---

HTTP Endpoints

Endpoint	Method	Description
/ or /mcp	POST	Streamable HTTP — initialize session or send requests
/ or /mcp	GET	SSE notification stream (requires Mcp-Session-Id header)
/ or /mcp	DELETE	Terminate session (requires Mcp-Session-Id header)
/sse	GET	Legacy SSE mode
/message	POST	Legacy SSE messages

---

Tools

NBS Core Query

Tool	Description
cnbs_search	Search by keyword, returns latest value — start here
cnbs_batch_search	Batch search multiple keywords in one call
cnbs_economic_snapshot	One-shot snapshot of 10 key Chinese macro indicators (GDP, CPI, PPI, PMI, unemployment, industrial output, retail sales, fixed investment, trade, M2)
cnbs_compare	Compare data across regions or time periods
cnbs_fetch_nodes	Get category tree nodes — accepts one or multiple categories
cnbs_fetch_metrics	Get indicator list — accepts one or multiple setIds
cnbs_fetch_series	Get time series data
cnbs_fetch_end_nodes	Recursively get all leaf nodes

NBS Reference

Tool	Description
cnbs_get_guide	Full tool guide (useful for LLMs to self-orient)
cnbs_get_regions	Region codes and names (GB/T 2260)
cnbs_get_categories	NBS category codes
cnbs_list_data_sources	All available data sources with tool mappings
cnbs_fetch_data_from_source	Fetch data from any named source
cnbs_get_source_categories	Categories for a given source
cnbs_search_in_source	Search within a specific source

World Bank

Tool	Description
ext_world_bank	Query a single indicator across countries and years
ext_world_bank_multi	Query multiple indicators at once
ext_world_bank_indicators	List all supported World Bank indicators

IMF

Tool	Description
ext_imf	Query IMF WEO data — accepts one or multiple indicators
ext_imf_indicators	List supported IMF indicators
ext_imf_all_indicators	Full IMF DataMapper indicator catalog

OECD

Tool	Description
ext_oecd	Query OECD SDMX data by dataset and key
ext_oecd_datasets	List supported OECD datasets

BIS

Tool	Description
ext_bis	Query BIS statistics — accepts one or multiple countries
ext_bis_datasets	List supported BIS datasets with key templates

FRED (Federal Reserve)

Tool	Description
ext_fred	Query FRED series — accepts one or multiple series
ext_fred_series	List all supported FRED series

China Extended Sources

Tool	Description
ext_cn_census	NBS census data (population, economic, agriculture)
ext_cn_department	NBS department statistics by ministry
ext_cn_department_list	All department categories and indicator keywords

Cross-Source Comparison

Tool	Description
ext_global_compare	Simultaneously query World Bank + IMF for the same indicator across countries

---

Quick Examples

China Economy At a Glance

// Full macro snapshot in one call
cnbs_economic_snapshot()

// Latest single indicator
cnbs_search(keyword="GDP")

// Batch indicators
cnbs_batch_search(keywords=["GDP", "CPI", "城镇化率", "出生率"])

// Regional comparison
cnbs_compare(keyword="GDP", regions=["北京", "上海", "广东"], compareType="region")

// Time series
cnbs_fetch_series(setId="...", metricIds=["..."], periods=["2015YY-2024YY"])

International Comparison

// China GDP growth vs peers (World Bank)
ext_world_bank(indicator="GDP_GROWTH", countries=["CHN","USA","DEU","JPN","IND"], startYear=2015)

// Multiple indicators for China
ext_world_bank_multi(indicators=["GDP_GROWTH","CPI","UNEMPLOYMENT"], countries=["CHN"], startYear=2010)

// IMF: single indicator
ext_imf(indicators="GDP_GROWTH", countries=["CHN","USA","JPN"], periods=["2022","2023","2024","2025"])

// IMF: multiple indicators in one call
ext_imf(indicators=["GDP_GROWTH","CPI_INFLATION","GOVT_DEBT"], countries=["CHN","USA"], periods=["2020","2021","2022","2023","2024"])

// World Bank + IMF side-by-side
ext_global_compare(wbIndicator="GDP_GROWTH", imfIndicator="GDP_GROWTH", countries=["CHN","USA","DEU","JPN"])

BIS & FRED

// BIS: single country
ext_bis(dataset="EER", countries="CN", lastNObservations=36)

// BIS: multiple countries in one call
ext_bis(dataset="EER", countries=["CN","US","DE","JP"], lastNObservations=24)

// BIS: credit gap
ext_bis(dataset="CREDIT_GAP", countries=["CN","US"], lastNObservations=20)

// FRED: single series
ext_fred(series="OIL_PRICE_WTI", limit=100, sortOrder="desc")

// FRED: multiple series in one call
ext_fred(series=["FED_FUNDS","CNY_USD","OIL_PRICE_WTI","GOLD_PRICE"], limit=30, sortOrder="desc")

NBS Census & Departments

// 2020 Population census
ext_cn_census(type="population")

// PBoC M2 monetary data
ext_cn_department(department="monetary", indicator="M2货币供应量")

// All finance ministry indicators
ext_cn_department(department="finance", fetchAll=true)

---

NBS Category Codes

Code	Category	Typical Indicators
1	Monthly	CPI, PPI, Industrial Output, PMI
2	Quarterly	GDP quarterly growth
3	Annual	GDP, population, urbanization rate
5	Provincial Quarterly	Provincial GDP by quarter
6	Provincial Annual	Provincial GDP, population by year
7	Other / Surveys	Household surveys, special surveys

NBS Time Format

• Annual: 2024YY, range ["2020YY-2024YY"]
• Quarterly: 2024A/B/C/D (A=Q1, B=Q2, C=Q3, D=Q4), shortcuts LAST6/LAST12/LAST18
• Monthly: 202401MM, range ["202301MM-202412MM"]

NBS Region Codes

Follows GB/T 2260 standard. Use cnbs_get_regions for the full list.

Region	Code
National	000000000000
Beijing	110000000000
Shanghai	310000000000
Guangdong	440000000000
Zhejiang	330000000000
Jiangsu	320000000000

---

Authentication

No authentication required by default. Enable Bearer token auth:

stdio / HTTP mode

npx mcp-statdb --port 12345 --auth-token your-secret-token
# or via env var
MCP_STATDB_AUTH_TOKEN=your-secret-token npx mcp-statdb --port 12345

Requests must then include:

Authorization: Bearer your-secret-token

Cloudflare Workers

npx wrangler secret put MCP_STATDB_AUTH_TOKEN

---

Development

npm install
npm run build
npm run start

Requirements

• Node.js >= 18.0.0
• Network access to data.stats.gov.cn, api.worldbank.org, www.imf.org, sdmx.oecd.org, stats.bis.org, api.stlouisfed.org

License

MIT