estat-mcp
e-Stat (政府統計の総合窓口) API client and MCP server for Japanese government statistics.
📝 日本語チュートリアル: Claude に聞くだけで GDP や CPI がわかる (Zenn)
What is this?
estat-mcp provides programmatic access to Japan's official statistics portal (e-Stat), which hosts 3,000+ statistical tables covering population, economy, prices, labor, agriculture, and regional data. It exposes these as both a Python async client and an MCP server for AI assistants.
Search statistics by keyword (人口, GDP, CPI, etc.)
Retrieve metadata to understand table structure (表章事項, 分類事項, 時間軸, 地域)
Fetch statistical data with automatic pagination for large datasets
Type-safe Pydantic models with Polars/pandas DataFrame export
Rate limiting built-in for API compliance
MCP server with 4 tools for Claude Desktop and other AI tools
Quick Start
Installation
pip install estat-mcp
# or
uv add estat-mcpGet an API Key
Register (free) at e-Stat API and set:
export ESTAT_APP_ID=your_app_id_here30-Second Example
import asyncio
from estat_mcp import EstatClient
async def main():
async with EstatClient() as client:
# Search for population statistics
tables = await client.search_stats("人口")
print(tables[0].name) # 人口推計
# Get metadata
meta = await client.get_meta(tables[0].id)
print(f"Time periods: {[t.name for t in meta.time_items]}")
# Fetch data (Tokyo, 2024)
data = await client.get_data(
tables[0].id,
cd_area="13000", # Tokyo
cd_time="2024000", # 2024
limit=100
)
# Export as DataFrame
df = data.to_polars()
print(df)
asyncio.run(main())CLI Quick Start
# Test API connectivity
estat-mcp test
# Search for CPI statistics
estat-mcp search "消費者物価指数" --limit 10
# Fetch data for a table
estat-mcp data 0003410379 --cd-area 13000 --format table
# Start MCP server
estat-mcp serveMCP Server
Add to your AI tool's MCP config:
{
"mcpServers": {
"estat": {
"command": "uvx",
"args": ["estat-mcp", "serve"],
"env": {
"ESTAT_APP_ID": "your_app_id_here"
}
}
}
}{
"mcpServers": {
"estat": {
"command": "uvx",
"args": ["estat-mcp", "serve"],
"env": {
"ESTAT_APP_ID": "your_app_id_here"
}
}
}
}Then ask your AI: "日本の人口統計を教えて" or "東京の最新CPIは？"
Available MCP Tools
Tool | Description |
| キーワードで統計テーブルを検索 |
| テーブル構造（表章事項・分類事項・時間軸・地域）を取得 |
| 統計データを取得（フィルタ・ページネーション対応） |
| 全ページ自動取得（max_pages制限付き） |
Python API
Search → Metadata → Data Flow
import asyncio
from estat_mcp import EstatClient
async def main():
async with EstatClient() as client:
# 1. Search for statistics tables
tables = await client.search_stats("消費者物価指数", limit=5)
# → [StatsTable(id="0003410379", name="消費者物価指数", ...), ...]
stats_id = tables[0].id
# 2. Get metadata to understand structure
meta = await client.get_meta(stats_id)
print(f"Table items: {[i.name for i in meta.table_items]}")
print(f"Time periods: {[t.name for t in meta.time_items]}")
print(f"Areas: {[a.name for a in meta.area_items]}")
# 3. Fetch data with filters
data = await client.get_data(
stats_id,
cd_area="13000", # Tokyo only
cd_time="2024000", # 2024 only
limit=1000
)
# 4. Export to DataFrame
df = data.to_polars()
print(df)
asyncio.run(main())Automatic Pagination
For large datasets, use get_all_data() to automatically fetch all pages:
# Fetch up to 10 pages (safety limit)
all_data = await client.get_all_data(
stats_id,
max_pages=10,
cd_cat01="100" # Filter by classification
)
print(f"Fetched {len(all_data.values)} / {all_data.total_count} records")Polars Export
# Requires: pip install estat-mcp[polars]
df = data.to_polars()CLI Reference
# Search for statistics tables
estat-mcp search <keyword> [options]
--limit, -n Max results (default: 20)
--format, -f Output format: table|json (default: table)
# Fetch statistical data
estat-mcp data <stats_id> [options]
--limit, -n Max records (default: 100)
--format, -f Output format: table|json (default: table)
--cd-tab Filter by table item code
--cd-time Filter by time code
--cd-area Filter by area code
--cd-cat01 Filter by classification code
# Test API connectivity
estat-mcp test
# Show version
estat-mcp version
# Start MCP server
estat-mcp serve [--transport stdio|sse]Available Data
e-Stat provides access to 3,000+ statistical tables:
Category | Examples |
Population | 人口推計、国勢調査、将来人口推計 |
Economy | GDP、企業統計、商業統計、工業統計 |
Prices | 消費者物価指数(CPI)、企業物価指数 |
Labor | 労働力調査、賃金構造基本統計調査 |
Trade | 貿易統計、国際収支統計 |
Agriculture | 農業センサス、漁業センサス、林野統計 |
Regional | 小地域・地域メッシュ、都道府県・市区町村データ |
Integration with edinet-mcp
estat-mcp works alongside edinet-mcp for comprehensive Japanese financial data:
edinet-mcp: Company financial statements (有価証券報告書)
estat-mcp: Macroeconomic and demographic statistics
Example workflow:
Use edinet-mcp to get Toyota's revenue from EDINET
Use estat-mcp to get auto industry production statistics
Compare company performance against industry trends
API Reference
EstatClient
from estat_mcp import EstatClient
async with EstatClient(
app_id="...", # or ESTAT_APP_ID env var
timeout=60.0, # request timeout
rate_limit=0.5, # requests per second
) as client:
# Search
tables: list[StatsTable] = await client.search_stats("人口", limit=20)
# Metadata
meta: StatsMeta = await client.get_meta("0003410379")
# Data (single page)
data: StatsData = await client.get_data(
"0003410379",
cd_area="13000",
cd_time="2024000",
limit=1000
)
# Data (all pages)
all_data: StatsData = await client.get_all_data(
"0003410379",
max_pages=10
)StatsData
# Access values
for v in data.values:
print(v.value) # The numeric value
print(v.time_code) # Time dimension code
print(v.area_code) # Area dimension code
print(v.classification_codes) # Dict of classification codes
# Export
json_data = data.to_dicts() # list[dict]
df = data.to_polars() # polars.DataFrame (requires polars)Response Format
e-Stat API uses XML-style conventions in JSON:
{
"TABLE_INF": [
{"@code": "110", "@name": "人口", "@unit": "人", "@level": "1"}
],
"VALUE": [
{"@tab": "110", "@time": "2024000", "@area": "13000", "$": "13960000"}
]
}@-prefixed keys are XML attributes$contains the text content
estat-mcp handles this automatically — you get clean Python objects.
Development
git clone https://github.com/ajtgjmdjp/estat-mcp
cd estat-mcp
uv sync --extra dev
uv run pytest -v # Run tests
uv run ruff check src/ # Lint
uv build # Build packageProject Structure
estat-mcp/
├── src/estat_mcp/
│ ├── __init__.py # Public API exports
│ ├── client.py # EstatClient (async HTTP)
│ ├── models.py # Pydantic models (StatsTable, StatsData, etc.)
│ ├── server.py # MCP server (FastMCP)
│ └── cli.py # Command-line interface
├── tests/ # Test suite
├── examples/ # Example scripts
├── pyproject.toml # Project configuration
└── README.mdData Attribution
This project uses data from e-Stat (政府統計の総合窓口), operated by the Statistics Bureau of Japan (総務省統計局). e-Stat data is provided under terms compatible with CC BY 4.0.
出典: 政府統計の総合窓口(e-Stat)（https://www.e-stat.go.jp/）
このサービスは、政府統計総合窓口(e-Stat)のAPI機能を使用していますが、サービスの内容は国によって保証されたものではありません。
This service uses the API of the Portal Site of Official Statistics of Japan (e-Stat). The content of this service is not guaranteed by the Japanese government.
Related Projects
edinet-mcp — EDINET financial data MCP server
jfinqa — Japanese financial QA benchmark
License
Apache-2.0