西安地方志 MCP Server

把西安地方志 App 自带的 6670 万字全文知识库接入你的 Agent（WorkBuddy / DeepSeek Harness / Trae / Claude Desktop / Cursor / Windsurf 等）。

全离线运行，不需要联网，不需要 API Key。

本工具只提供查询接口，数据来源见下方「数据库从哪来」。

数据库从哪来（二选一）

方式 A：从本仓库下载（推荐单独使用 MCP 的用户）

在 Releases 下载 xianzhi.db（v0.1.1 起为 v2 压缩版，60.7 MB，文字版），放到 xianzhi-mcp.exe 同级目录即可被自动发现。

该库由 西安地方志 App 的公开数据整理而成：38,978 篇 / 66,343,013 字，来源为政府公开信息（xadfz.xa.gov.cn）。

下载校验（SHA256，v0.1.1）：xianzhi.db = 490cc846941ede592ad87c250146c16e3b0abfc4756401f220f2229d5af3b983；xianzhi-mcp.exe = ce3f07fb2eecccaa5ac80f482a0362bf054a601d79471d1f3f85f8db2f4bbc9d。

方式 B：用西安地方志 Windows 版自带的数据库

如果你已经装了 西安地方志 App（EXE 安装版或便携版），数据库已经在你本机，无需再下载：

xianzhi-mcp.exe 会自动发现它（优先级见「第 2 步」），直接进入「第 3 步」接入 Agent 即可。

两个来源对比

优先图文版：目录中同时存在 xianzhi_img.db 与 xianzhi.db 时，自动选图文版（字数更多）。

数据库格式自动识别：本工具同时支持两种库格式，无需任何配置——

• v2：正文按块 zlib 压缩存于 blocks 表（本仓库 v0.1.1 起 Release 下载的 xianzhi.db 约 60.7 MB；西安地方志 App v0.4.0 起内置）， 由本工具解压后检索，结果与 v1 完全一致（已做 38,978 篇逐篇校验）；

• v1：正文直存 arts.body（v0.3.2 及更早 App 安装包自带，约 166.6 MB）。 区别只在首次全库检索稍慢约 0.5 秒（解压开销），查询接口与返回结构不变。

Related MCP server: genai-lab

3 步上手

第 1 步：拿到 exe 和数据库

• exe：在 Releases 下载 xianzhi-mcp.exe（单文件，约 31 MB，无需安装 Python）。

• 数据库：采用上节「方式 A」，就在同一 Releases 页下载 xianzhi.db；采用「方式 B」，则已在本机，跳过。

第 2 步：放对位置

把 xianzhi-mcp.exe（以及方式 A 下载的 xianzhi.db）放到一起，exe 会自动发现数据库：

自动发现优先级（找不到才往下走）：

1. --db 参数 / XIANZHI_DB 环境变量指定的文件或目录

2. exe 同级目录

3. exe 所在目录下的 app/resources/data/、resources/data/、data/

4. XIANZHI_HOME/data/（对应 App 的 -Dxianzhi.home）

5. %APPDATA%\xianzhi\data\

6. 当前工作目录

优先图文版：目录里同时有 xianzhi_img.db 和 xianzhi.db 时，自动选图文版（信息更全）。 想强制指定，用 --db 或 XIANZHI_DB。

第 3 步：接入你的 Agent

WorkBuddy（腾讯）

WorkBuddy（5.3 及以上版本）通过用户目录下的 mcp.json 添加自定义 MCP Server：

注意文件名是 mcp.json（不是 .mcp.json）。

写入以下内容（把路径换成你自己的 exe 路径，已有配置请合并进 mcpServers，不要覆盖）：

{
  "mcpServers": {
    "xianzhi-knowledge-base": {
      "command": "D:/xianzhi-app/xianzhi-mcp.exe",
      "args": []
    }
  }
}

保存后回到 WorkBuddy「连接器管理」页面，找到该 Server 点击「信任」，再新开会话（或重启当前会话），7 个地方志工具即被注入。

DeepSeek Harness（DSH）

DeepSeek Harness 目前处于开发者预览阶段，通过 MCP Apps 插件接入第三方 stdio Server（社区插件 @creative-dswork/dsh-uni-editor，即原 dsh-mcp-apps）：

# 1. 安装插件到 web profile
dsh plugin --profile web add @creative-dswork/dsh-uni-editor

在 $DSH_HOME/profiles/web/cordis.patch.yml 中加入（YAML；路径建议用正斜杠）：

- id: mcp-apps
  config:
    servers:
      - serverName: xianzhi-knowledge-base   # 只能含字母数字下划线连字符，最长 32
        transport: stdio
        command: "D:/xianzhi-app/xianzhi-mcp.exe"
        args: []
        forwardWorkspace: false              # 本服务只读本地库，不需要工作区

随后 dsh web 启动，工具列表会自动同步为 xianzhi_* 系列。

Trae IDE

写入 .trae/mcp.json（项目根目录）或 Trae 设置 → MCP Servers：

{
  "mcpServers": {
    "xianzhi-knowledge-base": {
      "command": "D:/xianzhi-app/xianzhi-mcp.exe",
      "args": []
    }
  }
}

Claude Desktop

写入 %APPDATA%/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "xianzhi-knowledge-base": {
      "command": "D:/xianzhi-app/xianzhi-mcp.exe",
      "args": []
    }
  }
}

Cursor

Settings → MCP Tools → Add New MCP Server：

• Type: command

• Command: D:/xianzhi-app/xianzhi-mcp.exe

Windsurf / Codeium

Settings → MCP Servers → Add Server：

{
  "xianzhi-knowledge-base": {
    "type": "stdio",
    "command": "D:/xianzhi-app/xianzhi-mcp.exe",
    "args": []
  }
}

把 D:/xianzhi-app/ 换成你自己的 exe 路径（Windows 路径建议用正斜杠 / 或双反斜杠 \\）。 更多模板见 mcp-config-examples.json。

重启 Agent，即可调用地方志知识库。

Agent 能用什么

推荐调用链：

xianzhi_stats                                    了解全貌
  → xianzhi_search("丝绸之路", category="西安市志")  找资料
    → xianzhi_get_article_chunked(id, 0, 10)       读前 10 段
      → xianzhi_get_article_chunked(id, 10, 10)    按需续读

所有结果都带完整层级路径（category → book_title → vol → path），Agent 能自行判断是否需要继续下钻。

常见问题

Q: Agent 报找不到 db？ 方式 A：把 xianzhi-mcp.exe 与 xianzhi.db 放同一目录；方式 B：把 exe 放到便携版解压目录根目录旁，或让它自动读 %APPDATA%\xianzhi\data\。也可直接设置 XIANZHI_DB=D:/你的路径/xianzhi.db。

Q: 没装西安地方志 App，能用吗？ 能。在 Releases 单独下载 xianzhi.db（v0.1.1 起 60.7 MB 的 v2 压缩版），与 exe 放同一目录即可，无需安装 App。

Q: 搜索结果太少？ xianzhi_search 是精确子串匹配（不分大小写、不分词）。换个关键词，比如搜「长安」而非「唐代长安」。

Q: 需要联网吗？ 不需要。全离线，直接读本机 xianzhi.db。

Q: 支持哪些数据库？ xianzhi.db（文字版）与 xianzhi_img.db（图文版）均可，自动优先图文版。

Q: 只读安全吗？ 数据库以 PRAGMA read_only = 1 打开，绝不会写入或修改你的志书库。

开发者

从源码运行

pip install -r requirements.txt
python xianzhi_mcp.py                        # 自动发现 db
python xianzhi_mcp.py --db D:/apps/xianzhi.db
python xianzhi_mcp.py --transport sse        # SSE 模式

打包单文件 exe

pip install pyinstaller typer
python build.py
# 产物：dist/xianzhi-mcp.exe（约 31 MB）

测试

# 数据层 + 自动发现（需先设置 XIANZHI_DB 或把 db 放在自动发现路径下）
python test_tools.py

# 完整 MCP 协议端到端（启动 exe 子进程，走 stdio 协议）
python test_mcp_client.py

命令行选项

xianzhi-mcp.exe                              # 自动发现 db，stdio 模式（默认）
xianzhi-mcp.exe --db D:/apps/xianzhi.db      # 显式指定 db 文件
xianzhi-mcp.exe --db D:/apps/data            # 显式指定目录（目录内优先图文版）
xianzhi-mcp.exe --transport sse              # SSE 模式，被远程 Agent 访问
XIANZHI_DB=D:/xxx/xianzhi_img.db xianzhi-mcp.exe

技术说明

• 数据库：SQLite（books + arts 两表；v2 压缩格式另含 meta/blocks 表），sqlite3 标准库直读 + zlib 解压，无第三方依赖

• 检索：LIKE 全表扫描（38978 篇约 1–3 秒）；标题命中排在正文命中之前

• 分块：正文按 \n\n 分割为段落，长文用 xianzhi_get_article_chunked 按需拉取

• 打包：PyInstaller --onefile，内置 Python 运行时，单文件分发

• MCP SDK：mcp >= 2.3.0（mcp.server.mcpserver.MCPServer）

相关项目

• xianzhi-app — 西安地方志全文离线 App（Android + Windows）

许可

代码采用 MIT License，Copyright (c) 2026 西安地名协会。 志书正文与配图版权归西安市地方志办公室所有。

数据来源

xianzhi.db 随本仓库 Release 一并分发，供未安装 App 的用户单独下载使用；数据来自政府公开信息 （西安市地方志办公室 / xadfz.xa.gov.cn），正文与配图版权归西安市地方志办公室所有，仅供检索使用。 若已安装 西安地方志 App，可直接使用其自带的数据库，无需重复下载。