Estat MCP

状态-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_here

30秒示例

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 serve

MCP服务器

添加到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工具

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多个统计表的访问：

与edinet mcp集成

estat mcp携手合作 edinet mcp 有关日本综合金融数据：

• edinet mcp：Company financial statements（有似证券报告书）
• 状态-mcp：宏观经济和人口统计

工作流程示例：

1. 使用edinet-mcp从edinet获得丰田的收入
2. 使用estat-mcp获取汽车行业生产统计数据
3. 将公司业绩与行业趋势进行比较

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