内容
# 开放研究MCP
[](https://pypi.org/project/openresearch-mcp/)
[](https://pypi.org/project/openresearch-mcp/)
[](LICENSE)
[](https://github.com/olanokhin/openresearch-mcp/actions/workflows/ci.yml)
[](https://registry.modelcontextprotocol.io)
零认证多源研究MCP服务器。适用于Claude Desktop、Cursor、OpenCode、Open WebUI或任何MCP兼容代理——无需API密钥。
## 工具列表
| 工具 | 来源 | 备注 |
| ---- | ------ | ----- |
| `web_search` | DuckDuckGo | 可选`site=`参数，用于限定搜索范围（例如`arxiv.org`） |
| `read_url` | 任意网页 | 去除导航和脚本，返回干净的文本 |
| `read_pdf` | 任意PDF或arXiv | 接受`/abs/`、`/pdf/`、`/html/` arXiv网址，可互换 |
| `search_openalex` | OpenAlex | 超过2.5亿篇论文，零速率限制；设置`OPENALEX_EMAIL`以使用礼貌池 |
| `search_hacker_news` | Hacker News（通过Algolia） | 带有积分和评论数的故事搜索 |
| `search_stackoverflow` | Stack Overflow API | 设置`STACKEXCHANGE_KEY`以获得更高的配额 |
| `read_repo` | GitHub公共仓库 | README + 文件树 + 关键文档；设置`GITHUB_TOKEN`以获得5k req/hr |
| `get_youtube_transcript` | YouTube字幕 | 接受完整网址、`youtu.be/`链接、短视频或纯视频ID |
## 安装
### 从MCP注册表（推荐用于Claude Desktop / Cursor）
服务器在[官方MCP注册表](https://registry.modelcontextprotocol.io)中列出，名称为`io.github.olanokhin/openresearch-mcp`。支持注册表的客户端可以自动发现并安装它——在客户端的MCP浏览器中搜索`openresearch-mcp`。
### 从PyPI
```bash
# 零安装，始终隔离——手动使用推荐
uvx openresearch-mcp
# 或全局安装
pip install openresearch-mcp
openresearch-mcp
```
默认情况下，服务器启动在`http://127.0.0.1:8000/mcp`（可流式HTTP，MCP 1.1+）——绑定到回环地址，因此不会暴露给本地网络。要暴露它（例如，在容器中或在网关后面），请显式绑定所有接口：
```bash
# 自定义端口
uvx openresearch-mcp --port 9000
# 绑定所有接口（仅在身份验证/速率限制网关后面）
uvx openresearch-mcp --host 0.0.0.0 --port 9000
```
> **注意：** 当绑定到回环地址以外时，请在前面添加身份验证/速率限制网关。服务器设计为零认证，并且`read_url`/`read_pdf`获取任意网址（阻止私有/链接本地/回环地址范围以防止SSRF，但速率限制由您负责）。
## 更新
```bash
# uvx
uvx --refresh openresearch-mcp
# pip
pip install --upgrade openresearch-mcp
```
## 连接到MCP客户端
### Claude Desktop
编辑`~/Library/Application Support/Claude/claude_desktop_config.json`
（Windows：`%APPDATA%\Claude\claude_desktop_config.json`）
```json
{
"mcpServers": {
"openresearch": {
"command": "uvx",
"args": ["openresearch-mcp", "--stdio"]
}
}
}
```
保存后重启Claude Desktop。服务器在stdio模式下运行——无需端口。
### Cursor
创建或编辑`~/.cursor/mcp.json`（全局）或`.cursor/mcp.json`（按项目）
```json
{
"mcpServers": {
"openresearch": {
"command": "uvx",
"args": ["openresearch-mcp", "--stdio"]
}
}
}
```
### HTTP代理（OpenCode、Open WebUI、自定义）
启动服务器：
```bash
uvx openresearch-mcp
# 或：openresearch-mcp
```
将您的代理指向：
```text
http://localhost:8000/mcp
```
## 可选环境变量
所有工具都无需密钥即可使用。设置这些变量以增加速率限制：
| 变量 | 效果 |
| -------- | ------ |
| `GITHUB_TOKEN` | GitHub：60 → 5,000 req/hr |
| `OPENALEX_EMAIL` | OpenAlex礼貌池（更高限制） |
| `STACKEXCHANGE_KEY` | Stack Overflow：更高每日配额 |
示例，使用密钥：
```bash
GITHUB_TOKEN=ghp_... OPENALEX_EMAIL=you@example.com uvx openresearch-mcp
```
或在Claude Desktop配置中：
```json
{
"mcpServers": {
"openresearch": {
"command": "uvx",
"args": ["openresearch-mcp", "--stdio"],
"env": {
"GITHUB_TOKEN": "ghp_...",
"OPENALEX_EMAIL": "you@example.com"
}
}
}
}
```
## 健康检查
在HTTP模式下运行时，检查哪些来源可达：
```bash
curl http://localhost:8000/health
```
```json
{
"status": "ok",
"sources": {
"duckduckgo": { "status": "ok", "latency_ms": 173 },
"github": { "status": "ok", "latency_ms": 101 },
"hacker_news": { "status": "ok", "latency_ms": 308 },
"stackoverflow": { "status": "ok", "latency_ms": 247 },
"openalex": { "status": "ok", "latency_ms": 412 },
"youtube": { "status": "ok", "latency_ms": 320 }
}
}
```
`status`为`"ok"`、`"degraded"`（某些来源不可用）或`"down"`（所有来源都不可用）。HTTP 200 / 503。
## 已知限制
- **Reddit / Zenodo**：阻止未经身份验证的爬取——未包含
- **YouTube**：大规模速率限制；适用于个人/低容量使用
## 路线图
- [ ] Reddit OAuth（基于浏览器，无用户密钥管理）
- [ ] GitHub设备流登录
- [ ] PubMed / NCBI（可选密钥）
- [ ] NewsAPI支持（可选密钥）
## 安全
openresearch-mcp使用 **[agent-security-skill](https://github.com/olanokhin/agent-security-skill)** 进行审查和强化，
这是一种OWASP对齐的AI代理安全审查技能，由维护者开发。
此次审查直接导致了该服务器的具体强化：SSRF抗性URL获取、工具输出的无信任内容框架、限定下载、固定的GitHub Actions、依赖项主要版本上限和安全敏感行为的回归测试。
在 **[SECURITY.md](SECURITY.md)** 中查看强化说明和当前安全状况。
## 许可证
Apache 2.0
<!-- mcp-name: io.github.olanokhin/openresearch-mcp -->
