arxiv-mcp-server

环境要求

• 已安装 uv（提供 uvx 命令；按 uv 官方文档安装）
• 支持 MCP 的客户端，如 Claude Desktop、Kiro 等
• 可选：Semantic Scholar 免费 API Key，用于 citation_graph 避免限流
• 无需克隆仓库，也无需手动配置 Python 环境

安装与启动步骤

1. 1安装 uv

   按 uv 官方文档安装 uv，它提供 uvx 命令；本服务器无需克隆仓库或搭建 Python 环境。

2. 2启动服务器

   首次运行会从 PyPI 拉取 arxiv-mcp-server，以 stdio 方式本地启动，默认论文目录为 ~/.arxiv-mcp-server/papers。

   uvx arxiv-mcp-server

   复制

3. 3写入客户端配置

   把这段 stdio 配置加入支持 mcpServers 结构的客户端（如 Claude Desktop、Kiro）；其他客户端可能用 servers 顶层对象、TOML 或设置界面。

   {
     "mcpServers": {
       "arxiv": {
         "type": "stdio",
         "command": "uvx",
         "args": ["arxiv-mcp-server"]
       }
     }
   }

   复制

4. 4自定义论文目录

   在客户端配置的 args 里追加 --storage-path 和绝对路径，即可更换论文、源码缓存与索引的存放位置。

   "args": ["arxiv-mcp-server", "--storage-path", "/absolute/path/to/papers"]

   复制

5. 5刷新到最新版

   uvx 会复用缓存的工具环境，若客户端缺少新工具，用该命令强制按当前 PyPI 版本重新解析，然后重启 MCP 客户端。

   uvx --python 3.11 --refresh-package arxiv-mcp-server arxiv-mcp-server

   复制

6. 6常驻命令安装

   想让 arxiv-mcp-server 直接出现在 PATH 上而不是通过 uvx 启动时可这样做；命令不可用时执行 uv tool update-shell 并重启终端。

   uv tool install arxiv-mcp-server
   uv tool update-shell

   复制

关键配置

如何确认成功

终端运行 uvx arxiv-mcp-server 不报错，客户端 MCP 列表中出现 arxiv 服务器并成功调用论文检索/阅读工具。

常见问题

注意事项

• 不要用 npm、pnpm 或 npx 安装同名包，那不是本项目。
• 环境变量名经 Pydantic settings 处理，大小写不敏感；但 --storage-path 是命令行参数而非环境变量。
• HTTP 模式默认绑定 127.0.0.1:8000，可用 HOST、PORT、ALLOWED_HOSTS、ALLOWED_ORIGINS 调整。
• 当前受支持的 PyPI 版本为 arxiv-mcp-server==0.7.2。