接入指南
让你的 AI 助手（Claude、Cursor 等）或命令行直接查询北京社区级人口数据。服务只返回汇总结果，不提供原始明细。
开始之前
需要准备三样东西：
- 一个 token，即你的个人访问凭据，向数据管理员申请。
- 能访问境外网站的网络。服务目前部署在 Cloudflare 上，国内直连不稳定，请开代理。
- 一个客户端：Claude Code、claude.ai 网页版或桌面端、Cursor，或者只用命令行（需要 Python 3）。
申请 token
- 联系本服务的数据管理员，说明你的姓名、单位和用途（比如“城建院张三，做朝阳区养老设施配置研究”）。
- 管理员会私信发给你一段消息，里面有 token 和接入命令。每人一个 token，请勿转发；需要给别人用，请让对方自己申请。
- 如果 token 泄露或不再需要，告诉管理员吊销即可，不影响其他人。
安装接入
按你用的客户端选一种，不需要都装。
在终端运行一行命令：
然后重启 Claude Code，输入 /mcp，能看到 bjdata 显示为已连接就成功了。直接问“劲松街道 60 岁以上老人有多少”试试。
- 打开 claude.ai，进入 设置 → Connectors（连接器），点 Add custom connector。
- 名称填
bjdata，URL 填下面这一行（token 已经包含在里面）： - 保存后，在对话框下方的工具菜单里启用 bjdata，就可以提问了。桌面端会同步网页版的设置。
Cursor、Windsurf、Cline 等支持 MCP 的工具，在 MCP 配置文件（Cursor 是 ~/.cursor/mcp.json）里加入：
保存后重启客户端，在 MCP 设置页看到 bjdata 已连接即可。
不用 AI 也可以直接在命令行查，适合批量导出表格。只需要 Python 3，不用装任何包。
macOS / Linux
Windows（PowerShell）
能列出工具清单就装好了。常用命令见下方“命令行速查”。
以后服务端更新了命令行客户端，你查询时会看到一行“有新版本”的提示，运行 bjdata update（Windows 是 python bjdata.py update）即可自动升级。用 AI 助手接入的方式不需要升级，服务端更新后自动生效。
怎么提问
接入 AI 助手后，用平常说话的方式提问就行，助手会自己选工具、确认地名。下面这些都能直接问：
- 劲松街道 22 到 35 岁的常住人口有多少，占比多少？街道级，可以用任意单岁区间
- 朝阳区 60 岁以上人口占比最高的 10 个社区是哪些？社区排名
- 给我海淀区每个社区的少儿、劳动年龄、老年人口和占比，导出成表格逐社区全表，可导出 CSV
- 以东经 116.4615、北纬 39.8845 为中心，800 米范围内有多少老年人？点加半径，按面积分摊
- 画一下东城区的人口金字塔单岁或 5 岁年龄结构
- 回龙观地区外来人口占比是多少？地名不确定时，助手会先帮你查准名称
建议在引用结果时，把助手返回的时点、口径说明一起带上。
命令行速查
| 想做什么 | 命令 |
|---|---|
| 查地名写法 | bjdata find 劲松 |
| 街道某年龄段人口 | bjdata pop --town 劲松街道 --age 22-35 |
| 社区人口 | bjdata pop --community 劲松西社区 --age 60- |
| 半径范围人口 | bjdata pop --lon 116.4615 --lat 39.8845 --r 800 |
| 年龄结构 | bjdata ages --district 东城区 --bin 5 |
| 排名 | bjdata rank --district 朝阳区 --age 60- --limit 10 |
| 逐社区全表（CSV） | bjdata table --district 海淀区 --csv > 海淀.csv |
| 自定义年龄段全表 | bjdata table --bands 0-14,20-34,60+,80+ --csv > 全市.csv |
| 边界 GeoJSON | bjdata boundary --town 劲松街道 > 劲松.geojson |
| 升级客户端 | bjdata update |
年龄写法：22-35 表示 22 到 35 岁，60- 表示 60 岁及以上，-14 表示 14 岁及以下。任何命令加 --json 输出原始 JSON。CSV 文件带 BOM，用 Excel 直接打开不会乱码。
可用工具
AI 助手看到的就是这些工具。一般不用记，了解一下能查什么即可。
| 工具 | 用途 |
|---|---|
find_areas | 按名称查街道、社区的规范写法和 adcode |
population_in_area | 一个范围内的常住人口、外来人口、某年龄段人数与占比 |
age_structure | 一个范围的年龄结构（人口金字塔数据） |
age_table | 逐社区或逐街道的分年龄段人数与占比全表 |
rank_areas | 按年龄占比、人口、外来人口占比、密度排名 |
get_boundary | 区、街道、社区的简化边界（GeoJSON） |
list_datasets / describe_dataset | 数据集清单和详细口径 |
查询范围可以是：全市、区、街道乡镇、单个社区、经纬度加半径（最大 5 公里），或者自己画的多边形（最大 500 平方公里）。
口径与隐私规则
两条隐私规则
| 查询范围 | 年龄区间 |
|---|---|
| 全市、区、街道乡镇 | 任意单岁区间，如 22-35 岁 |
| 社区、半径范围、自定义多边形，以及只含 1 个社区的街道 | 年龄边界自动取整到 5 岁，如 22-35 岁会变成 20-34 岁；返回结果里会注明 |
另外，任何少于 10 人的数字都显示为 <10，对应的占比显示为空。这是隐私保护，不是缺数据。
使用数据前请了解
- 时点是 2020 年 11 月 1 日（七普标准时点），社区边界是 2023 版。七普之后撤并调整过的社区，是按名称匹配挂接上去的。
- 有 274 个社区（约 148 万人）的总人口是用人口栅格估算的，返回结果中的
n_estimated或is_estimated会标出来，引用时请注明。 - 年龄占比的分母是单岁年龄合计（
age_sum），不是常住人口pop_total。两者全市只差 0.02%，但个别社区差得较多，自己计算占比时不要混用。 - 半径和多边形查询按面积比例分摊，假设社区内人口均匀分布。对面积大的村庄，或含大片绿地、水面的社区，误差会比较大。
- 边界坐标是 WGS84 近似值，适合分析和制图，不是测绘级精度。
常见问题
提示“未授权”（401）
提示“查询服务正在启动”（503），或者第一次查询特别慢
连不上，或者超时
HTTPS_PROXY 环境变量。为什么我查 22-35 岁，结果写的是 20-34 岁？
服务更新后我需要做什么？
bjdata update 升级即可。能拿到原始数据或单岁明细吗？
结果能和其他数据叠加吗？
age_table 和 find_areas 都返回 12 位 adcode，可以作为主键关联；get_boundary 返回的边界是 WGS84 坐标的 GeoJSON，能直接拖进 QGIS。