arxivZH MCP

把 arXiv、DOI 或论文网页链接对应的 LaTeX 源码批量译为简体中文，并用 XeLaTeX 编译出中文 PDF。 固定使用 DeepSeek 官方 deepseek-flash；多篇论文并行处理，单篇内部串行，支持术语表、结构校验、断点续跑和编译 QA。

输出固定在 <work_dir>/arxivZH/：

<work_dir>/arxivZH/
  <arxiv_id>v<version>/    # 中文 .tex 源码、glossary.json、manifest.json、编译日志与页面预览
  PDFzh/<arxiv_id>v<version>.zh.pdf
  .jobs/<job_id>.json     # 任务记录（进度、用量、逐篇结果）

无 TeX 源码的论文会跳过（回退查 arXiv），不做 PDF 文本翻译。

环境要求

• macOS（密钥存于 macOS Keychain，其他系统需改 arxiv_zh/network.py 中的密钥读取）

• Python >= 3.11、uv、网络可访问 api.deepseek.com

• MacTeX（ctex / Fandol 字体 / XeLaTeX / latexmk）、Poppler（pdftoppm / pdftotext）

• 一个 DeepSeek API 密钥（仅查询模型列表不收费，翻译按 token 计费）

Related MCP server: Paper Search MCP Server

安装

方式一：一键安装（macOS + Codex CLI）

git clone https://github.com/FjkFjkFjk314/arxiv-zh-mcp.git
cd arxiv-zh-mcp
python3 install.py

install.py 会：复制运行时到 ~/.local/share/arxiv-zh-mcp/ 并 uv sync； 把 skill 装到 ~/.agents/skills/arxiv-zh/；向 Codex 注册 MCP（不改动其他 MCP 配置）。 它不读写任何 API 密钥。

方式二：手动安装（任意 MCP 客户端）

git clone https://github.com/FjkFjkFjk314/arxiv-zh-mcp.git
cd arxiv-zh-mcp
uv sync                          # 创建 .venv 并安装依赖
chmod +x run.sh setup-keychain.command

然后按客户端注册 stdio MCP，启动命令为仓库内的 run.sh 绝对路径：

• Codex：codex mcp add arxiv-zh -- /绝对路径/arxiv-zh-mcp/run.sh

• Claude Code：claude mcp add arxiv-zh /绝对路径/arxiv-zh-mcp/run.sh

• Claude Desktop / Cursor（JSON 配置）：

{
  "mcpServers": {
    "arxiv-zh": {
      "command": "/绝对路径/arxiv-zh-mcp/run.sh"
    }
  }
}

注册后新开一个会话加载工具。

配置 API 密钥

macOS 上双击（或终端执行）安装目录里的 setup-keychain.command， 在隐藏输入中粘贴 DeepSeek 密钥，保存到 Keychain 的 arxiv-zh-deepseek / api-key 条目。 密钥不作为 CLI/MCP 参数，不写入任何配置或日志。配置前可先跑：

.venv/bin/python cli.py status            # 本机依赖与 Keychain 检查
.venv/bin/python cli.py status --check-api  # 附加查询模型权限（不产生翻译请求）

MCP 工具

关键约定（写进给 agent 的 skill，见 skill/arxiv-zh/SKILL.md）：

• work_dir 必须显式传用户当前工作目录的绝对路径，不能用 MCP 安装目录。

• 提交后每 15–30 秒轮询同一 job_id；不因等待或超时而重新提交。

• 完成后要实际查看返回的 qa.previews 页面图像；visual_review: pending 不算版式验收。

• 失败先读错误与日志，再对同一 job_id 续跑；中断块可能重复计费，不要无上限重试。

给其他 agent 的一句话用法

翻译论文：先 arxiv_zh_status() 确认就绪，再 translate_papers(links=[...], work_dir="<当前工作目录绝对路径>")， 保存返回的 job_id 并每 15–30 秒调 get_translation() 轮询，完成后打开返回的 PDF 路径与预览图验收。

并行限制

• 按 2026-09-23 官方并发定义，deepseek-flash 额度为 2500 个同时在途请求（不是 RPM），本机取 60%，即 1500。

• 同一系统用户的所有 arxivZH 工作目录共用 API 请求槽位；API 请求完成或异常退出会释放槽位，重试退避和等待编译不占用 API 槽位。其他程序或其他电脑使用同一账号的请求不在本机控制范围内。

• 每批最多 50 篇、每篇同时最多 1 个 API 请求，所以单批实际最多 50 路；同一工作目录仍只允许一个活动任务。上限不会预先发起空请求。

• 论文术语表、译文缓存和用量彼此独立；结果保持输入顺序，progress.papers 提供按输入序号区分的进度，progress.finished 提供已结束条目数。

• PDF 编译在本机串行排队，不占 API 槽位。模型额度为经核对的固定配置；不会自动抓取网页更改上限或更换模型。

可通过 arxiv_zh_status().concurrency 查看当前配置。一次提交全部待译论文即可启用论文级并行，无需逐篇创建任务。链接解析按输入顺序进行，已解析论文随即进入处理；arXiv 下载继续遵守跨任务约 3 秒的请求间隔。

实测范围（2026-09-23）：已用已安装运行时并行翻译两份短 TeX 样例，记录到真实 DeepSeek HTTP 请求重叠；6 次生成请求均返回 HTTP 200，两份中文 PDF 均编译成功并通过页面检查。此次验证了 2 路实际并发，未对 50 路或 1500 路进行线上满载测试。详见 验证记录。

使用 Skill

skill/arxiv-zh/ 是完整的 agent skill（SKILL.md + agents 配置），按你的 agent 的 skill 机制放置即可：

• 通用约定：cp -R skill/arxiv-zh ~/.agents/skills/arxiv-zh（项目级则放 <项目>/.agents/skills/）

• Codex / Kimi Code 等识别 ~/.agents/skills/ 的客户端放这里即可

之后对 agent 说：

使用 arxiv-zh 翻译 https://arxiv.org/abs/1706.03762，放到当前工作目录。

CLI（不依赖 MCP，推荐作为兜底通道）

MCP 工具未加载时可直接用 CLI，功能等价：

.venv/bin/python cli.py status [--check-api]
.venv/bin/python cli.py translate --work-dir /绝对/工作目录 <链接...> [--main-tex 相对路径]
.venv/bin/python cli.py get --work-dir /绝对/工作目录 <job_id>
.venv/bin/python cli.py resume --work-dir /绝对/工作目录 <job_id>

测试

uv sync --dev
.venv/bin/python -m pytest -q        # 离线测试

包含模拟 API 的真实 XeLaTeX 编译流水线、断点续跑、公式/引用保护、恶意压缩包防护、 DOI/标题匹配歧义、论文级并行、跨进程限流、异常退出后释放槽位和 MCP stdio 握手。 2026-09-23 共 46 项测试通过。离线测试不证明 DeepSeek 账户或翻译质量； 真实在线验证记录见 VERIFICATION.md。

行为与边界

• 官方模型固定为 deepseek-flash，Chat Completions 非思考模式。密钥未配置或模型不可用时明确报错，不替换模型。

• 术语表先行：按论文上下文采用国内学术界通行译名，全文一致；数学、代码、作者姓名、参考文献著录、专名与图片保持原样。数学环境和图片内的英文不翻译。自定义宏作为 TeX 代码整体保护。

• 不保留英文 TeX 或原始压缩包；完成的文件原位替换为中文，.bib/.bbl/.sty/.cls 和图片保留，无 original/ 副本。

• 分块保护结构、公式、路径和引用，校验标记顺序与数值，失败最多重试一次；通过的块按内容哈希缓存，文件以哈希 + 原子写入记进度；检测到外部修改时停止覆盖。

• 网络断连不自动重复付费请求；手动续跑可能重做未确认的当前块。

• 一批最多 50 篇，论文之间并行，单篇内部的文件与分块串行；arXiv 请求跨任务间隔约 3 秒；单篇失败不阻塞其他篇；相同链接列表重复提交返回原任务。

• DOI 优先精确匹配 arXiv，标题回退要求高相似度并核对作者；歧义即跳过。普通 PDF 链接只尝试文献元数据解析，不做 PDF 文本翻译。

• 解包拒绝路径穿越、符号链接和超限文件；编译禁用 shell escape 与用户 latexmkrc，限制 TeX 文件读写。仍应使用可信论文源；本工具不是通用 TeX 沙箱。

• 成功 PDF 必须通过中文文本、缺字、未解析引用检查，并生成页面预览与溢出警告。

参考

• DeepSeek Chat Completions

• arXiv API

• Model Context Protocol

许可

MIT，见 LICENSE。