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