Semanticscholarmcp

🚀 语义学者MCP服务器

语义学者MCP服务器是一个模型上下文协议（MCP）服务器，它提供对语义学者学术图谱API的访问。借助该服务器，你可以搜索学术论文、作者，还能获取有关引用和参考文献的详细信息。

🚀 快速开始

此MCP服务器能让你轻松访问语义学者学术图谱API，搜索学术资源并获取详细信息。你可按以下步骤进行安装和配置。

✨ 主要特性

• 论文搜索：使用各种过滤器搜索学术论文。
• 论文详情：获取特定论文的详细信息。
• 批量论文检索：一次性获取多篇论文的信息。
• 作者搜索：按姓名查找作者。
• 作者详情：获取作者的详细信息及其发表的论文。
• 引用分析：获取引用特定论文的其他论文。
• 参考文献分析：获取特定论文引用的其他论文。
• 引用上下文：获取一篇论文引用另一篇论文的上下文。
• 文本片段搜索：在学术论文中搜索文本片段。
• PDF下载：以合适的文件名和元数据下载开放获取的PDF文件。
• PDF可用性检查：在下载前检查PDF文件是否可用。
• 智能命名：以论文标题和年份作为文件名保存PDF文件。
• 元数据支持：在PDF文件属性中嵌入标题、作者和年份信息。

📦 安装指南

1. 克隆此仓库：

git clone <repository-url>
cd SemanticScholarMCP

2. 安装依赖项：

pip install -r requirements.txt

3. （可选但推荐）设置你的语义学者API密钥：

export SEMANTIC_SCHOLAR_API_KEY="your-api-key-here"

注意：API密钥是可选的。即使不设置，服务器也能正常工作，但你将共享公共速率限制（所有未认证用户每秒最多1000个请求）。

4. （可选）安装PDF元数据支持：

pip install -e ".[metadata]"

📚 详细文档

开发

设置开发环境

# 安装开发依赖项
pip install -e ".[test,dev]"

运行测试

# 运行所有测试
make test

# 仅运行单元测试（快速，无API调用）
make test-unit

# 运行集成测试（需要API密钥）
export SEMANTIC_SCHOLAR_API_KEY="your-api-key"
make test-integration

# 运行性能测试
make test-performance

代码质量

# 运行代码检查
make lint

# 格式化代码
make format

配置

将此服务器添加到你的MCP客户端配置中：

{
  "mcpServers": {
    "SemanticScholarMCP": {
      "command": "/Users/your-username/Desktop/SemanticScholarMCP/venv/bin/python",
      "args": ["/Users/your-username/Desktop/SemanticScholarMCP/src/semantic_scholar_mcp/server.py"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

无API密钥的配置（共享公共速率限制）：

{
  "mcpServers": {
    "SemanticScholarMCP": {
      "command": "/Users/your-username/Desktop/SemanticScholarMCP/venv/bin/python",
      "args": ["/Users/your-username/Desktop/SemanticScholarMCP/src/semantic_scholar_mcp/server.py"]
    }
  }
}

重要提示：

• 请将 your-username 替换为你实际的用户名。
• API密钥是可选的，但推荐使用以获得更高的速率限制。
• 无API密钥：所有用户共享公共速率限制（每秒1000个请求）。
• 使用免费API密钥：你将拥有更高的专属速率限制。

可用工具

论文工具

search_papers

使用各种过滤器搜索学术论文。

参数：

• query（必需）：搜索查询字符串。
• limit：最大结果数（默认：10，最大：100）。
• offset：跳过的结果数（默认：0）。
• fields：要返回的字段列表，以逗号分隔。
• publication_types：按出版类型过滤。
• open_access_pdf：过滤具有开放获取PDF的论文。
• min_citation_count：最小引用次数。
• year：出版年份或年份范围（例如，"2020 - 2023"）。
• venue：出版场所。

get_paper

获取特定论文的详细信息。

参数：

• paper_id（必需）：论文ID（语义学者ID、DOI、arXiv ID等）。
• fields：要返回的字段列表，以逗号分隔。

get_paper_batch

在单个请求中获取多篇论文的信息。

参数：

• paper_ids（必需）：论文ID列表，以逗号分隔。
• fields：要返回的字段列表，以逗号分隔。

作者工具

search_authors

按姓名搜索作者。

参数：

• query（必需）：作者姓名或搜索查询。
• limit：最大结果数（默认：10，最大：1000）。
• offset：跳过的结果数（默认：0）。
• fields：要返回的字段列表，以逗号分隔。

get_author

获取特定作者的详细信息。

参数：

• author_id（必需）：作者ID。
• fields：要返回的字段列表，以逗号分隔。

引用和参考文献工具

get_paper_citations

获取引用特定论文的其他论文。

参数：

• paper_id（必需）：要获取引用的论文ID。
• limit：最大结果数（默认：10，最大：1000）。
• offset：跳过的结果数（默认：0）。
• fields：要返回的字段列表，以逗号分隔。

get_paper_references

获取特定论文引用的其他论文。

参数：

• paper_id（必需）：要获取参考文献的论文ID。
• limit：最大结果数（默认：10，最大：1000）。
• offset：跳过的结果数（默认：0）。
• fields：要返回的字段列表，以逗号分隔。

get_citation_context

获取一篇论文引用另一篇论文的上下文。

参数：

• paper_id（必需）：被引用论文的ID。
• citing_paper_id（必需）：引用论文的ID。

文本搜索工具

search_snippets

在学术论文中搜索文本片段。

参数：

• query（必需）：文本片段搜索查询。
• limit：最大结果数（默认：10，最大：100）。
• offset：跳过的结果数（默认：0）。

PDF工具

get_paper_pdf_info

检查论文的PDF可用性。

参数：

• paper_id（必需）：要检查PDF可用性的论文ID。

download_paper_pdf

如果论文的PDF可用，则下载该PDF，使用论文标题作为文件名并设置元数据。

参数：

• paper_id（必需）：要下载PDF的论文ID。
• download_path：保存PDF的目录（默认：~/Downloads/semantic_scholar_papers）。

特性：

• 使用论文标题作为文件名（例如，"Machine Learning in Healthcare (2023).pdf"）。
• 在PDF元数据中设置标题、作者和出版年份。
• 自动处理重复文件名。
• 创建有组织的文件夹结构。

💻 使用示例

搜索机器学习相关论文

search_papers("machine learning", limit=5, year="2023")

获取特定论文的详细信息

get_paper("10.1038/nature14539")

查找引用特定论文的其他论文

get_paper_citations("10.1038/nature14539", limit=10)

搜索作者

search_authors("Geoffrey Hinton")

获取引用上下文

get_citation_context("paper-id-1", "paper-id-2")

检查PDF可用性

get_paper_pdf_info("10.1038/nature14539")

下载论文PDF

download_paper_pdf("10.1038/nature14539")

这将保存PDF文件，文件名类似：

"Deep learning (2015).pdf"

文件中嵌入了包括标题、作者（LeCun, Y., Bengio, Y., Hinton, G.）和年份（2015）的元数据。

API速率限制

语义学者API有以下速率限制：

• 无API密钥：所有未认证用户共享每秒1000个请求的速率限制（在高流量时可能会受到限制）。
• 使用免费API密钥：你将拥有更高的专属速率限制。

为确保性能稳定，建议获取免费API密钥。

🔧 技术细节

故障排除

速率限制错误

如果你看到以下错误：

Error: Rate limit exceeded. Please wait a moment and try again, or get an API key for higher limits.

这意味着你已达到共享公共速率限制，或者由于高流量API受到限制。

即时解决方案：

1. 获取免费API密钥（推荐）：

   • 访问 https://www.semanticscholar.org/product/api 。
   • 注册免费账户。
   • 获取你的API密钥。
   • 将其添加到你的Claude桌面配置中：

   "env": {
     "SEMANTIC_SCHOLAR_API_KEY": "your-actual-api-key-here"
   }
   

   • 重启Claude桌面应用。

2. 等待并重试：共享公共速率限制可能只是暂时超出。

3. 使用较小的结果限制：减少查询中的 limit 参数。

4. 分散请求：避免连续快速发出多个请求。

配置问题

• 确保配置中的Python路径指向正确的虚拟环境。
• 验证服务器脚本路径是否正确。
• 检查虚拟环境中是否安装了所有依赖项。

测试连接

你可以通过让Claude以较小的限制搜索单篇论文来测试服务器是否正常工作：

search_papers("machine learning", limit=1)

错误处理

所有工具都包含全面的错误处理，如果请求失败或API返回错误，将返回详细的错误消息。

📄 许可证

本项目采用MIT许可证 - 详情请参阅 LICENSE 文件。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。