arXiv Research MCP

用于科学文献研究的只读、可部署 MCP 服务器。

ChatGPT
   ↓  Streamable HTTP
arXiv Research MCP
   ↓  official Atom API
arXiv scientific papers

该服务器负责检索和规范化元数据。ChatGPT 仍负责解释物理学、比较论文以及推导方程。

工具

每个工具都标记为只读，并返回类型化的结构化数据，包含 arXiv ID、规范化标题和摘要、作者、分类、日期、DOI、期刊参考文献、摘要 URL，以及 PDF URL（如有）。

本地设置

需要 Python 3.11 或更高版本。

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Copy-Item .env.example .env

编辑 .env 中的 ARXIV_USER_AGENT，将示例联系信息替换为你的邮箱或项目 URL。arXiv 不需要 API 密钥。

通过 stdio 在本地运行：

arxiv-mcp

在本地运行远程兼容的传输方式：

arxiv-mcp --transport streamable-http --host 127.0.0.1 --port 8000

端点为：

http://127.0.0.1:8000/mcp
http://127.0.0.1:8000/health

如需手动测试工具，请启动 HTTP 服务器，运行官方 MCP Inspector，并将其连接到 http://127.0.0.1:8000/mcp：

npx @modelcontextprotocol/inspector@latest

运行测试

pytest
ruff check .

测试使用模拟的 HTTP 响应，不会消耗 arXiv API。GitHub Actions 会在每次推送和拉取请求时运行相同的检查。

可靠性与安全性

• 固定的白名单上游：https://export.arxiv.org/api/query

• 默认全局请求间隔为三秒

• 对超时、网络故障、HTTP 429 和临时 5xx 响应进行有界重试

• 严格的结果、偏移量、分类、排序和 arXiv-ID 校验

• 安全的 XML 解析，禁用外部实体

• 无 shell 执行、任意 URL 抓取、密钥、写操作或用户数据存储

• 无状态 Streamable HTTP 部署

在 Render 上部署

仓库包含非 root 的 Dockerfile 和 render.yaml Blueprint。

1. 将此仓库推送到 GitHub。

2. 登录 Render 并选择 New → Blueprint。

3. 连接 GitHub 仓库并应用 render.yaml。

4. 在 Render 服务环境中，修改 ARXIV_USER_AGENT，加入你的真实联系邮箱或仓库 URL。

5. 等待 /health 通过，然后复制服务 URL。

最终的 MCP URL 为：

https://<your-render-service>.onrender.com/mcp

Blueprint 使用 Render 的免费实例，因此部署不会悄然产生计费承诺。Render 文档说明，免费服务在闲置 15 分钟后休眠，重启大约需要一分钟。这种冷启动可能超过 MCP 客户端的超时时间；在将其作为始终可用的生产连接器之前，请将服务升级为 starter 或其他付费实例。请参阅 Render 免费层级限制 和 Blueprint 参考。

连接到 ChatGPT

以下步骤遵循 OpenAI 当前的官方文档：

1. 部署服务器并确认公共 HTTPS /mcp URL 在 MCP Inspector 中可用。

2. 在 ChatGPT 中，打开 Settings → Security and login 并启用 Developer mode。

3. 打开 ChatGPT Plugins 并选择 plus 按钮。

4. 填写：

   • 名称：arXiv Research

   • 描述：Read-only search and metadata retrieval from the official arXiv API.

   • 连接：公共 MCP 端点

   • 服务器 URL：https://<your-render-service>.onrender.com/mcp

   • 认证：无

5. 创建连接并确认恰好发现五个工具。

6. 开始新聊天，从工具菜单中添加 arXiv Research。

OpenAI 目前要求公共 HTTPS 端点（或其 Secure MCP Tunnel）和 Streamable HTTP，通常位于 /mcp。Developer mode 的可用性取决于账户和工作区策略。OpenAI 当前页面并未承诺每个指定的 ChatGPT 套餐都提供该模式，因此你的账户上是否存在 Developer mode 开关才是权威判断。如果 Plus 账户未显示该开关，服务器仍可通过 MCP Inspector、其他 MCP 客户端或 OpenAI API Playground 使用。请参阅 OpenAI 当前连接指南 和 MCP 服务器指南。

示例 ChatGPT 提示

• Search arXiv for recent quantum gravity papers.

• Find papers about the Bondi-Sachs formalism.

• Search hep-th for path integral approaches to gravity.

• Find papers by Roger Penrose related to general relativity.

• Get the metadata and PDF link for arXiv:2401.12345.

项目结构

.
├── src/arxiv_mcp/
│   ├── arxiv_client.py
│   ├── config.py
│   ├── models.py
│   └── server.py
├── tests/
├── .github/workflows/ci.yml
├── .env.example
├── Dockerfile
├── render.yaml
├── pyproject.toml
└── README.md

MIT 许可。