Shanghai Library Open Data MCP server

上海图书馆开放数据 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 等都能用）。

为什么安全？ 项目代码里不含任何钥匙，钥匙只在你自己的电脑 / 配置里，不会被别人看到。

数据源与致谢

衷心感谢上海图书馆官方开放数据平台提供权威、丰富且持续维护的历史文献与文脉数据接口。本项目的全部核心数据能力（99 个 webapi）均建立在上海图书馆开放数据之上，若无官方的开放与授权，本项目无从实现。

• 上海图书馆开放数据平台（官方）：https://opendata.library.sh.cn/opendata/

• 搜韵诗词：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 个官方接口 + 搜韵诗词
• 🔑 密钥由使用者提供：通过环境变量 SLCAPIKEY 或工具参数 key 传入，代码不内置任何密钥
• 🐍 零第三方依赖：仅用 Python 标准库（urllib + json），无需 pip install
• 🎵 AIGC 歌词素材：souyunpoem 免 token 检索 199 万首诗词（按作者/标题/诗句/朝代/体裁/韵部），souyunrhyme / souyun_couplet 提供韵典和对仗词汇
• 📚 RAG 骨架：rag_kb.py 纯标准库 TF-IDF 知识库，可离线灌入官方 ZIP 数据

工具总览

接口家族：近代城市文化(20)、古籍循证(15)、国漫革命文献(7)、武康路历史(7)、纪年表关联数据(5)、韬奋纪念馆(4)、书目数据(4)、家谱(4)、地名纪年(4)、竞赛PDF文献(3)、知识图谱人物(2)、文化总库机构(2)、舆图(2)、手迹(2)、红色旅游事件(2)、地名志(2)、纪年(2)、人名规范库(1)、机构名录(1)、戏单(2)、其他(8)。

快速开始

本地 stdio 接入

# 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 服务：

{
  "mcpServers": {
    "上海图书馆开放数据": {
      "command": "python3",
      "args": ["/绝对路径/slc_mcp_server.py"],
      "env": { "SLC_API_KEY": "你的上图书APIKey" }
    }
  }
}

通过 PyPI / uvx 安装（推荐，跨客户端通用）

发布到 PyPI 后，任意支持 MCP 的客户端都能用一条命令拉起，无需克隆仓库：

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（slcmcphttp.py，纯标准库实现）：

• POST /mcp 处理 JSON-RPC（initialize 时签发 Mcp-Session-Id，通知类返回 202）
• GET /mcp 提供 SSE 流
• 已开启 CORS，便于网页端 / 远程网络调用

适合网页版 AI、手机端，或多人共用同一服务；需自行把服务跑在可访问的地址上。个人在编辑器本地使用，stdio 已足够，无需此模式。

客户端配置示例

三种客户端本质都是同一段 mcpServers JSON，区别只在配置文件路径。下面的示例用 uvx 拉起（免克隆仓库）；想用本地脚本，把 command/args 换成 ["python3","/绝对路径/slcmcpserver.py"] 即可。

WorkBuddy（本机已配置过一份） 配置文件：~/.workbuddy/mcp.json。本机已存在一份指向本地脚本 + Key 的配置，只需在连接器管理界面对「上海图书馆开放数据」点击 信任 即可在本会话启用；也可替换成下面的 uvx 写法。

{
  "mcpServers": {
    "上海图书馆开放数据": {
      "command": "uvx",
      "args": ["shanghai-library-open-data-mcp"],
      "env": { "SLC_API_KEY": "你的上图书APIKey" }
    }
  }
}

Cursor 配置文件：项目根目录 .cursor/mcp.json 或全局 ~/.cursor/mcp.json（同一段 JSON）。

Shortened. The full README is on GitHub.