PaperClaw

Give your AI Agent the power to search, crawl, and research — at scale.

专为科研场景打造的 MCP 搜索服务器，聚合网络搜索、网页爬取、学术文献与专利检索，开箱即用接入 Claude / Cursor / Cline

为什么选择本项目？

市面上大多数 MCP 搜索工具只能做通用网络搜索。PaperClaw 专为科研 AI Agent 设计：

🔬 学术优先 — 同时聚合 7 大学术平台，自动去重、合并字段、补全 DOI 与开放获取链接
🤖 AI 原生 — 可选 LLM 重排序与结构化摘要生成，返回 agent_remark 字段，让 Agent 直接消费
⚡ 生产就绪 — 多 Key 轮换、请求缓存、并发控制、错误重试，稳定跑在服务器上
🔌 零改造接入 — 标准 MCP 协议，配置一行 URL 即可接入任意 MCP 客户端

✨ 功能模块

模块	说明
🌐 网络搜索	SerpAPI / Serper 双引擎，多 Key 自动轮换，结果智能缓存
🕷️ 网页爬取	FireCrawl 驱动，支持自建服务优先 + 云端自动回退，返回干净 Markdown
📚 学术搜索	7 平台并发聚合 → 去重合并 → LLM 重排序 → DOI 补全 → OA 链接发现 → AI 摘要
🔬 专利搜索	Google Patents + Lens.org 多平台聚合，支持 AI 摘要与重排序

📚 学术搜索支持平台

平台	类型	说明
OpenAlex	元数据	全量开放学术图谱，免费无限制
Semantic Scholar	元数据 + 语义	AI 驱动的引用分析
Google Scholar	全文索引	覆盖最广，含灰色文献
arXiv	预印本	物理 / CS / 数学领域必备
PubMed	生物医学	NCBI 权威医学文献库
Crossref	DOI 注册	权威 DOI 来源，元数据补全
InfoXMed	中文医学	中文医学文献与指南

🚀 快速开始

1. 安装依赖

推荐使用 uv：

uv sync

pip install -e .

2. 配置环境变量

cp .env.example .env

编辑 .env，至少填入以下密钥：

# 网络搜索（二选一）
SERPAPI_API_KEY=your_serpapi_key    # https://serpapi.com
SERPER_API_KEY=your_serper_key      # https://serper.dev

# 网页爬取
FIRECRAWL_API_KEY=your_firecrawl_key  # https://www.firecrawl.dev

# AI 摘要（可选，OpenAI 兼容接口）
PAPERSEARCH_LLM_BASEURL=https://your-openai-compatible-host/v1
PAPERSEARCH_LLM_APIKEY=your_llm_key

📄 完整配置项见 .env.example 或下方环境变量参考

3. 启动服务

uv run main.py

服务运行于 http://localhost:8000，交互式文档见 /docs。

4. 接入 MCP 客户端

在 Claude Desktop / Cursor / Cline 配置文件中添加：

{
  "mcpServers": {
    "paperclaw-mcp": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

重启客户端后，AI 即可直接调用搜索、爬取、学术检索等工具。

🐳 Docker 部署

# 1. 准备配置
cp .env.example .env
# 编辑 .env 填入 API Keys

# 2. 启动
docker compose up -d

# 3. 查看日志
docker compose logs -f

📡 API 参考

端点	方法	功能
`/mcp`	—	MCP 协议入口
`/api/serpapi`	`POST`	网络搜索
`/api/firecrawl`	`POST`	网页爬取
`/api/paper_search`	`POST`	学术文献搜索
`/api/patent_search`	`POST`	专利搜索

curl -X POST "http://localhost:8000/api/paper_search" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "transformer attention mechanism",
    "platforms": ["arXiv", "OpenAlex", "SemanticScholar"],
    "final_limit": 10,
    "summary_enabled": false
  }'

参数说明：

platforms 为空时使用全部默认平台
final_limit 受 PAPERSEARCH_FINAL_LIMIT_MAX 上限限制
summary_enabled=true 时调用 LLM 生成 agent_remark 字段

curl -X POST "http://localhost:8000/api/patent_search" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "neural network accelerator",
    "limit": 10
  }'

curl -X POST "http://localhost:8000/api/firecrawl" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://arxiv.org/abs/1706.03762"
  }'

⚙️ 环境变量参考

变量	说明	默认值
`SERPAPI_API_KEY`	SerpAPI 密钥（逗号分隔可配多个，自动轮换）	—
`SERPER_API_KEY`	Serper 密钥	—
`SEARCH_ENABLE`	启用引擎：`SERPAPI` \| `SERPER`	—
`FIRECRAWL_API_KEY`	FireCrawl 云端密钥	—
`SELF_FIRECRAWL_SERVER`	自建 FireCrawl 地址（优先于云端）	—
`FIRECRAWL_PRIORITY`	加载顺序，如 `SELF,CLOUD`	`CLOUD`

变量	说明	默认值
`PAPERSEARCH_PER_PLATFORM_LIMIT`	每平台抓取数量	`10`
`PAPERSEARCH_FINAL_LIMIT`	最终返回数量	`10`
`PAPERSEARCH_FINAL_LIMIT_MAX`	用户可设置的上限	`50`
`PAPERSEARCH_SUMMARY_ENABLED`	启用 AI 摘要	`true`
`PAPERSEARCH_LLM_BASEURL`	LLM 接口（OpenAI 兼容）	—
`PAPERSEARCH_LLM_APIKEY`	LLM API Key	—
`PAPERSEARCH_SUMMARY_MODELNAME`	摘要模型名	—
`PAPERSEARCH_SEMANTICSCHOLAR_API_KEY`	Semantic Scholar Key（可选）	—
`PAPERSEARCH_CORE_API_KEY`	CORE OA Key（可选）	—
`PAPERSEARCH_CONTACT_EMAILS`	礼貌邮箱，改善部分平台限速	—

变量	说明	默认值
`PATENTSEARCH_ENABLED`	启用专利搜索	`true`
`PATENTSEARCH_PER_PLATFORM_LIMIT`	每平台抓取数量	`50`
`PATENTSEARCH_FINAL_LIMIT`	最终返回数量	`10`
`PATENTSEARCH_SUMMARY_ENABLED`	启用 AI 摘要	`true`
`PATENTSEARCH_LLM_BASEURL`	LLM 接口	—
`PATENTSEARCH_LLM_APIKEY`	LLM API Key	—
`LENS_API_KEY`	Lens.org API Key（可选）	—

📁 项目结构

.
├── main.py                      # 应用入口
├── src/
│   ├── api.py                   # REST API 端点
│   ├── model.py                 # 请求/响应数据模型
│   ├── config.py                # 全局配置
│   ├── paper_search/            # 学术搜索模块
│   │   ├── search.py            # 核心流程编排
│   │   ├── platforms/           # 各平台适配器
│   │   ├── models.py            # Paper 数据模型
│   │   └── llm.py               # LLM 调用封装
│   └── patent_search/           # 专利搜索模块
│       ├── search.py
│       ├── platforms/
│       └── models.py
├── tests/                       # 测试用例
├── assets/                      # 静态资源
├── .env.example                 # 环境变量模板
├── docker-compose.yaml
└── pyproject.toml

🤝 贡献

欢迎 Issue 和 Pull Request！详见 CONTRIBUTING.md。

遇到问题？→ 提交 Issue 有新想法？→ 发起 Discussion

📄 许可证

本项目基于 AGPL-3.0 协议开源。

✅ 个人使用、学术研究、开源项目集成（需保持开源）
❌ 商业使用须单独授权 → [email protected]

Made with ❤️ by Postroggy @ SCNU

如果这个项目对你有帮助，欢迎点一个 ⭐

Paperclaw MCP

README