状态-mcp
电子统计 （政府统计の総合窗口）API client and MCP server for Japanese government statistics.
📝 日语教程：只听Claude就能知道GDP和CPI（Zenn）
这是什么？
状态-mcp 提供对日本官方统计门户的程序化访问(电子统计)，其中包含3000多个统计表，涵盖人口、经济、价格、劳动力、农业和地区数据。它将这些作为Python异步客户端和 主控程序 用于AI助手的服务器。
- 按关键字搜索统计数据（人口、GDP、CPI等）
- Retrieve metadata to understand table structure（表章事项，分类事项，时间轴，地域）
- 为大型数据集自动分页获取统计数据
- 类型安全的Pydantic模型 使用Polars/pandas DataFrame导出
- 速率限制 内置以符合API
- MCP服务器，配备4个用于Claude Desktop和其他AI工具的工具
快速开始
安装
pip install estat-mcp
# or
uv add estat-mcp获取API密钥
注册（免费） 电子统计API 并设置：
export ESTAT_APP_ID=your_app_id_here30秒示例
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快速入门
# 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服务器
添加到AI工具的MCP配置中：
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)
{
"mcpServers": {
"estat": {
"command": "uvx",
"args": ["estat-mcp", "serve"],
"env": {
"ESTAT_APP_ID": "your_app_id_here"
}
}
}
}Cursor (~/.cursor/mcp.json)
{
"mcpServers": {
"estat": {
"command": "uvx",
"args": ["estat-mcp", "serve"],
"env": {
"ESTAT_APP_ID": "your_app_id_here"
}
}
}
}请教“日本人口统计”或“东京最新CPI”？"
可用的MCP工具
| 工具 | 说明 |
|---|---|
search_statistics 用关键字搜索统计表 | |
get_statistic_meta 获取表结构（表章事项、分类事项、时间轴、地域） | |
get_statistic_data 获取统计数据（支持筛选分页） | |
get_all_statistic_data 全页自动获取（max_pages受限） |
Python API
搜索→ 元数据→ 数据流
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())自动分页
对于大型数据集，请使用 get_all_data() 要自动获取所有页面，请执行以下操作：
# 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出口
# Requires: pip install estat-mcp[polars]
df = data.to_polars()CLI参考
# Search for statistics tables
estat-mcp search [options]
--limit, -n Max results (default: 20)
--format, -f Output format: table|json (default: table)
# Fetch statistical data
estat-mcp data [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]可用数据
e-Stat提供对3000多个统计表的访问：
| 类别 | 示例 |
|---|---|
| 人口 | 人口推计、国势调查、将来人口推计 |
| 经济 | GDP、企业统计、商业统计、工业统计 |
| 价格 | 消费者物似指数（CPI）、企业物似指数 |
| 劳动 | 劳働力调查、赁金构造基本统计调查 |
| 贸易 | 贸易统计、国际收支统计 |
| 农业 农业普查、渔业普查、林野统计 | |
| 区域 小地区、地区网格、都道府县、市区町村数据 |
与edinet mcp集成
estat mcp携手合作 edinet mcp 有关日本综合金融数据：
- edinet mcp：Company financial statements（有似证券报告书）
- 状态-mcp：宏观经济和人口统计
工作流程示例：
- 使用edinet-mcp从edinet获得丰田的收入
- 使用estat-mcp获取汽车行业生产统计数据
- 将公司业绩与行业趋势进行比较
API 参考
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)响应格式
e-Stat API在JSON中使用XML样式约定：
{
"TABLE_INF": [
{"@code": "110", "@name": "人口", "@unit": "人", "@level": "1"}
],
"VALUE": [
{"@tab": "110", "@time": "2024000", "@area": "13000", "$": "13960000"}
]
}@-前缀键是XML属性$包含文本内容
estat-mcp会自动处理这个问题——你会得到干净的Python对象。
发展
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 package项目结构
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.md数据归因
此项目使用以下数据 电子统计 （政府统计的综合窗口）， operated by the Statistics Bureau of Japan（総务省统计局）. e-Stat数据是根据与以下条款兼容的条款提供的 CC 4.0.
出典：政府统计の総合窗口（e-Stat）（https://www.e-stat.go.jp/）
此服务使用政府统计信息综合窗口（e-Stat）的API功能，但服务内容不受国家担保。 该服务使用日本官方统计门户网站（e-Stat）的API。这项服务的内容不受日本政府的保证。
相关项目
- edinet mcp --EDINET金融数据MCP服务器
- jfin的 --日本金融质量保证基准
许可证
阿帕奇-2.0