io.github.FreyaBit/shanghai-library-open-data-mcp
This server provides 12 MCP tools that bridge the Shanghai Library Open Data platform and the Souyun poetry database, enabling AI assistants to query historical Chinese cultural data, genealogy, poetry, and more.
Shanghai Library Data (requires API key):
slc_era: Convert between Chinese historical dynasty/reign eras and Gregorian calendar years.slc_jiapu: Search genealogy records by family name or title.slc_building: Search historical buildings on Wukang Road by keyword.slc_red_event: Search red tourism and historical revolutionary events by date or keyword.slc_api: A generic dispatcher to call any of the 97+ official web APIs (ancient books, films, maps, calligraphy, etc.).slc_raw: Direct GET requests to any data1.library.sh.cn path.
Discovery & Info (no API key needed):
slc_endpoints: List all 99 available API endpoints with IDs, families, paths, and parameters; filterable by family.slc_datasets: View dataset overviews and third-party institutions.slc_sparql: Access SPARQL query capabilities.
Souyun Poetry Database (no API key needed, 1.99M poems):
souyun_poem: Search poems by author, title, verse, dynasty, genre, or rhyme.souyun_rhyme: Look up rhyme categories, allusions, and poetry examples for characters (useful for lyric writing).souyun_couplet: Find antithetical words for couplet composition.
The server integrates with AI tools like WorkBuddy, Cursor, and Claude Desktop via stdio or Streamable HTTP.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@io.github.FreyaBit/shanghai-library-open-data-mcp 帮我查一下武康路有哪些历史建筑"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
上海图书馆开放数据 MCP
把上海图书馆开放数据平台的 99 个 webapi 接口 + 搜韵诗词库(199 万首,免 token)封装成 12 个 MCP 工具,可接入 WorkBuddy、Cursor、Claude Desktop 等任意 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 客户端一键接入。
Related MCP server: io.github.lacausecrypto/poetrydb
特性
🧩 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 |
| 列出全部 99 个接口(id/家族/路径/参数),发现能力 | ❌ |
| 通用分发器:调用任意 webapi 接口 | ✅ |
| 中国历史纪年表:朝代/年号 ↔ 公元年 | ✅ |
| 家谱谱目检索 | ✅ |
| 武康路历史建筑检索 | ✅ |
| 红色旅游/历史事件检索 | ✅ |
| 任意 data1 路径 GET 兜底调用 | ✅ |
| 数据集总览 / SPARQL 说明 | ❌ |
| 搜韵诗词检索(199 万首,免 token) | ❌ |
| 韵典:查字所属韵部、典故、诗例 | ❌ |
| 对仗词汇 | ❌ |
接口家族:近代城市文化(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(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 写法。
{
"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 放在工具参数里:
{ "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 # 协议冒烟测试Available Tools
12 toolsslc_apiA
通用分发器:调用 api_2025 注册的全部 webapi 接口(家谱/古籍/盛档/人名库/碑帖/电影/期刊/舆图/书目/地名志/武康路 等 97 个)。endpoint 填接口 id;params 填查询参数(JSON);path_args 填路径占位{0}{1};key 填自己的上海图书馆开放数据 APIKey(必填)。先用 slc_endpoints 查 id。
Inputs: endpoint (required), key, params, path_args.
slc_buildingC
武康路历史建筑检索(已验证可用)
Inputs: keyword (required), key.
slc_datasetsB
数据集与第三方机构总览
Inputs: no named parameters.
slc_endpointsA
列出全部可用 webapi 接口(id/家族/路径/参数),可按 family 过滤。用于发现能力。
Inputs: family.
slc_eraA
中国历史纪年表:输入朝代/年号返回公元年范围,或反之。例:明 -> 1368~1644。请传入 key(自己的上海图书馆开放数据 APIKey)。
Inputs: term (required), key.
slc_jiapuB
家谱谱目检索(data1)。可按谱名/姓氏检索
Inputs: key, title, familyname.
slc_rawA
任意 data1.library.sh.cn 路径的 GET 兜底调用
Inputs: path (required), key, params.
slc_red_eventC
红色旅游/历史事件检索
Inputs: key, date, keyword.
slc_sparqlC
SPARQL 图查询说明(该平台 Key 仅网页端可用)
Inputs: no named parameters.
souyun_coupletA
搜韵对仗词汇:返回与输入字/词对仗的词汇(免token),写对仗句用
Inputs: word (required).
souyun_poemA
搜韵诗词检索(免token):按作者/标题/诗句/朝代/体裁/韵部查诗词,服务 AIGC 歌词。
Inputs: keyword (required), type, rhyme, scope, +2 more.
souyun_rhymeA
搜韵韵典:查字所属韵部、词末/词首典故、句末诗例(免token)
Inputs: char (required), qtype.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools have distinct purposes (e.g., souyun_rhyme vs souyun_couplet), but slc_api and slc_raw both provide generic access to library data, and slc_sparql is documentation rather than a query tool. This creates some boundary confusion.
All names use lowercase with underscores and follow a prefix_noun pattern (souyun_* and slc_*). The convention is consistent, though not verb-noun based, and the mix of prefixes is acceptable.
12 tools is within the typical well-scoped range, but includes a few near-redundant access methods (slc_api, slc_raw, slc_endpoints) and a documentation-only tool (slc_sparql). Slightly heavy but reasonable for the combined library/poetry scope.
The library domain is nearly complete thanks to the generic slc_api dispatcher covering 97 endpoints, plus dedicated tools for key resources. The poetry tools cover rhyme, couplet, and poem search. Minor gaps exist (e.g., no direct SPARQL execution), but agents can work around them.
Maintenance
Related MCP Connectors
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
TravelMind: 8 MCP tools for travel (12306 trains, flights, hotels, geocode, planning, policy).
Discover and call 10,000+ production APIs from one MCP server. Pay-per-call billing for AI agents.
Related MCP Servers
- AlicenseCqualityDmaintenanceAggregates multiple third-party APIs into unified MCP tools, providing out-of-the-box access to 10 popular services including OpenWeather, Google Maps, GitHub, Notion, Spotify, and more. Enables users to interact with weather data, search places, manage repositories, create content, and access various web services through a single MCP server.34MIT
- AlicenseBqualityDmaintenanceEnables exploring and retrieving classic poems from PoetryDB via 12 MCP tools for catalog, search, and discovery, including by author, title, lines, and poetic forms.1250 npm2MIT
- AlicenseNot gradedqualityBmaintenanceEnables LLM clients to access A-share market data, run the trading rule engine, and retrieve daily decision reports through 32 MCP tools.MIT
- AlicenseAqualityBmaintenanceEnables AI agents to search 1m+ open-access papers, standards, textbooks, and legal documents, resolve identifiers such as RFCs, DOIs, and legal citations, download PDFs, and retrieve citations and metadata through MCP tools.9MIT