{
  "markdown": "# 上海图书馆开放数据 MCP\n\n[![smithery badge](https://smithery.ai/badge/haoplaytime/shanghai-library-open-data-mcp)](https://smithery.ai/servers/haoplaytime/shanghai-library-open-data-mcp)\n\n把上海图书馆开放数据平台的 **99 个 webapi 接口** + 搜韵诗词库（199 万首，免 token）封装成 12 个 MCP 工具，可接入 WorkBuddy、Cursor、Claude Desktop 等任意 MCP 客户端。\n\n<!-- mcp-name: io.github.FreyaBit/shanghai-library-open-data-mcp -->\n\n> **这是啥？** 一个把「上海图书馆开放数据」接进 AI 助手的桥。装好之后，你直接在 AI 工具里说\"查武康路的历史建筑\"\"找首写月亮的诗\"，AI 就会自动去上海图书馆的数据里查，再把结果讲给你听——不用懂接口、不用写代码。\n>\n> **你要准备什么？** 两样：① 去上海图书馆开放数据平台免费注册，拿一把\"钥匙\"（APIKey）；② 按下面的「快速开始」把项目接进你常用的 AI 编辑器（Cursor、Claude Desktop、VS Code、WorkBuddy 等都能用）。\n>\n> **为什么安全？** 项目代码里**不含任何钥匙**，钥匙只在你自己的电脑 / 配置里，不会被别人看到。\n\n---\n\n## 数据源与致谢\n\n- **上海图书馆开放数据平台（官方）**：https://opendata.library.sh.cn/opendata/\n  衷心感谢**上海图书馆官方**开放数据平台提供权威、丰富且持续维护的历史文献与文脉数据接口。本项目的全部核心数据能力（99 个 webapi）均建立在上海图书馆开放数据之上，若无官方的开放与授权，本项目无从实现。\n- **搜韵诗词**：https://api.sou-yun.cn/open （199 万首诗词，免 token）\n- 本仓库接口版权归各数据方所有，使用请遵守各平台开放数据的使用条款；调用方须使用自己在平台注册的 APIKey，本仓库不内置、不收集任何密钥。\n- 本项目已发布至 PyPI、MCP 官方 Registry（`io.github.FreyaBit/shanghai-library-open-data-mcp`）、Smithery、ModelScope 与 GitHub，便于各 MCP 客户端一键接入。\n\n## 特性\n\n- 🧩 **12 个 MCP 工具**：覆盖家谱 / 古籍 / 碑帖 / 武康路 / 书目 / 地名志 / 红色事件 / 纪年表 / 电影 / 舆图 / 手迹 / 人名库 / 戏单等 99 个官方接口 + 搜韵诗词\n- 🔑 **密钥由使用者提供**：通过环境变量 `SLC_API_KEY` 或工具参数 `key` 传入，代码不内置任何密钥\n- 🐍 **零第三方依赖**：仅用 Python 标准库（urllib + json），无需 `pip install`\n- 🎵 **AIGC 歌词素材**：`souyun_poem` 免 token 检索 199 万首诗词（按作者/标题/诗句/朝代/体裁/韵部），`souyun_rhyme` / `souyun_couplet` 提供韵典和对仗词汇\n- 📚 **RAG 骨架**：`rag_kb.py` 纯标准库 TF-IDF 知识库，可离线灌入官方 ZIP 数据\n\n## 工具总览\n\n| 工具 | 说明 | 需要 Key |\n|---|---|---|\n| `slc_endpoints` | 列出全部 99 个接口（id/家族/路径/参数），发现能力 | ❌ |\n| `slc_api` | 通用分发器：调用任意 webapi 接口 | ✅ |\n| `slc_era` | 中国历史纪年表：朝代/年号 ↔ 公元年 | ✅ |\n| `slc_jiapu` | 家谱谱目检索 | ✅ |\n| `slc_building` | 武康路历史建筑检索 | ✅ |\n| `slc_red_event` | 红色旅游/历史事件检索 | ✅ |\n| `slc_raw` | 任意 data1 路径 GET 兜底调用 | ✅ |\n| `slc_datasets` / `slc_sparql` | 数据集总览 / SPARQL 说明 | ❌ |\n| `souyun_poem` | 搜韵诗词检索（199 万首，免 token） | ❌ |\n| `souyun_rhyme` | 韵典：查字所属韵部、典故、诗例 | ❌ |\n| `souyun_couplet` | 对仗词汇 | ❌ |\n\n> 接口家族：近代城市文化(20)、古籍循证(15)、国漫革命文献(7)、武康路历史(7)、纪年表关联数据(5)、韬奋纪念馆(4)、书目数据(4)、家谱(4)、地名纪年(4)、竞赛PDF文献(3)、知识图谱人物(2)、文化总库机构(2)、舆图(2)、手迹(2)、红色旅游事件(2)、地名志(2)、纪年(2)、人名规范库(1)、机构名录(1)、戏单(2)、其他(8)。\n\n## 快速开始\n\n### 本地 stdio 接入\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/FreyaBit/OpenSH-mcp.git\ncd OpenSH-mcp\n\n# 2. 设置你的 APIKey（在上海图书馆开放数据平台获取）\nexport SLC_API_KEY='你的上图书APIKey'    # macOS/Linux\n# $env:SLC_API_KEY='你的上图书APIKey'    # Windows PowerShell\n\n# 3. 运行端到端自测\npython3 tests/test_stdio.py\n```\n\n在你的 MCP 客户端里配置 stdio 服务：\n\n```json\n{\n  \"mcpServers\": {\n    \"上海图书馆开放数据\": {\n      \"command\": \"python3\",\n      \"args\": [\"/绝对路径/slc_mcp_server.py\"],\n      \"env\": { \"SLC_API_KEY\": \"你的上图书APIKey\" }\n    }\n  }\n}\n```\n\n### 通过 PyPI / uvx 安装（推荐，跨客户端通用）\n\n发布到 PyPI 后，任意支持 MCP 的客户端都能用一条命令拉起，无需克隆仓库：\n\n```bash\nuvx shanghai-library-open-data-mcp              # 本地 stdio（默认）\nuvx shanghai-library-open-data-mcp --transport http --port 8080      # Streamable HTTP 远程（进阶可选）\n```\n\n客户端配置只需：`command: uvx, args: [\"shanghai-library-open-data-mcp\"]`。\n\n### Streamable HTTP 传输（进阶，可选）\n\n除 stdio 外，本服务原生支持 Streamable HTTP（`slc_mcp_http.py`，纯标准库实现）：\n- `POST /mcp` 处理 JSON-RPC（initialize 时签发 `Mcp-Session-Id`，通知类返回 202）\n- `GET /mcp` 提供 SSE 流\n- 已开启 CORS，便于网页端 / 远程网络调用\n\n> 适合网页版 AI、手机端，或多人共用同一服务；需自行把服务跑在可访问的地址上。个人在编辑器本地使用，stdio 已足够，无需此模式。\n\n## 客户端配置示例\n\n三种客户端本质都是同一段 `mcpServers` JSON，区别只在配置文件路径。下面的示例用 `uvx` 拉起（免克隆仓库）；想用本地脚本，把 `command`/`args` 换成 `[\"python3\",\"/绝对路径/slc_mcp_server.py\"]` 即可。\n\n**WorkBuddy（本机已配置过一份）**\n配置文件：`~/.workbuddy/mcp.json`。本机已存在一份指向本地脚本 + Key 的配置，只需在连接器管理界面对「上海图书馆开放数据」点击 **信任** 即可在本会话启用；也可替换成下面的 `uvx` 写法。\n```json\n{\n  \"mcpServers\": {\n    \"上海图书馆开放数据\": {\n      \"command\": \"uvx\",\n      \"args\": [\"shanghai-library-open-data-mcp\"],\n      \"env\": { \"SLC_API_KEY\": \"你的上图书APIKey\" }\n    }\n  }\n}\n```\n\n**Cursor**\n配置文件：项目根目录 `.cursor/mcp.json` 或全局 `~/.cursor/mcp.json`（同一段 JSON）。\n\n**Claude Desktop / Claude Code**\n- Claude Desktop：把上面的 `mcpServers` 合并进 `%APPDATA%\\Claude\\claude_desktop_config.json`（Windows）或 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）。\n- Claude Code 命令行：`claude mcp add 上海图书馆开放数据 -- uvx shanghai-library-open-data-mcp`\n\n> 说明：12 个工具里 `souyun_poem` / `souyun_rhyme` / `souyun_couplet` / `slc_endpoints` 免 Key 开箱即用，其余 8 个需要 `SLC_API_KEY`。已发布到 PyPI、MCP 官方 Registry（`io.github.FreyaBit/shanghai-library-open-data-mcp`）、Smithery、ModelScope、GitHub，均可一键拉起。\n\n## APIKey 说明\n\n- 上海图书馆开放数据平台要求**每个调用者使用自己的 APIKey**（在平台注册后获取）。\n- 本仓库**不包含任何 Key**，也不记录、不收集你的 Key。\n- Key 读取优先级：**工具参数 `key`** > 环境变量 `SLC_API_KEY`。\n- 调用需要 Key 的工具时，把 Key 放在工具参数里：\n\n```json\n{ \"endpoint\": \"building_list\", \"params\": { \"freetext\": \"武康路\" }, \"key\": \"你的上图书APIKey\" }\n```\n\n- 免 Key 工具（`souyun_poem` / `souyun_rhyme` / `souyun_couplet` / `slc_endpoints`）开箱即用。\n- ⚠️ 请勿把你的 Key 配置到公开服务的环境变量里（等于公开给所有调用者）。\n\n## 目录结构\n\n```\nOpenSH-mcp/\n├── README.md                 # 本文件\n├── pyproject.toml            # PyPI 打包配置（uvx 入口）\n├── slc_mcp_server.py         # MCP 服务主程序（stdio，纯标准库）\n├── slc_mcp_http.py           # Streamable HTTP 传输层（纯标准库，进阶可选）\n├── slc_endpoints.py          # 99 个 webapi 接口注册表（自动生成）\n├── gen_endpoints.py          # 接口注册表生成器（从官方 API 文档解析）\n├── souyun_poem.py            # 搜韵诗词/韵典/对仗采集（免 token）\n├── rag_kb.py                 # RAG 知识库骨架（纯标准库 TF-IDF）\n├── mcp.json.template         # MCP 客户端配置模板（不含 Key）\n└── tests/                    # 测试（从环境变量读 Key，缺失会提示）\n    ├── test_stdio.py         #   stdio 端到端（协议 + 真实调用）\n    ├── test_live.py          #   handler 级实测（GET/POST/搜韵）\n    └── test_mcp.py           #   协议冒烟测试\n```\n",
  "bytes": 5518,
  "sha": "780a263bc48863f06c261a6f648def94ad0ca7787573cc940c6869d1e9014c47",
  "repo_slug": "freyabit/opensh-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_freyabit_shanghai_library_open_81d06dc7/readme"
}