OpenAlex MCP Server

OpenAlex MCP 服务

此项目提供了一个 Model Context Protocol（MCP）服务，使 AI Agent 和其他 MCP 客户端能够与 OpenAlex 数据库交互，重点关注学术著作。它使用 pyalex Python 库与 OpenAlex API 通信，并使用 MCP Python SDK（fastmcp）将功能作为 MCP 工具开放。

示例

以下是一些示例查询，可供启用了此 MCP 的 AI Agent 参考：

• 找出引用了介绍卷积神经网络的奠基性论文的 5 篇被引次数最多的论文
• 我正在寻找与自监督视觉里程计相关的论文。请找出与该主题相关的论文，然后阅读每篇论文的标题和摘要，并为其评定 1 到 10 分的相关性评分。
• 找出 2020 年以来发表的、关于 Transformer 模型的最具影响力的论文，并总结其架构的发展历程
• 找出由 MIT 和 Stanford 的研究人员共同撰写的论文

功能

此服务提供以下 MCP 工具，用于与 OpenAlex 作品交互：

1. search_works：

   • 描述： 根据关键词和筛选条件搜索 OpenAlex 作品。搜索查询支持布尔运算符。返回所选字段，并使用游标分页。
   • 参数：
     • search_query（字符串，必填）：搜索词。
     • filters（对象，可选）：用于筛选的键值对（例如，{"publication_year": 2023, "is_oa": true}）。可用键请参阅 OpenAlex 筛选条件文档。
     • search_field（字符串，可选，默认值："default"）：要搜索的字段（'title'、'abstract'、'fulltext'、'title_and_abstract'、'default' - 搜索标题、摘要和全文）。
     • select_fields（字符串数组，可选）：要返回的根级字段列表（例如，["id", "doi", "title", "abstract"]）。如果请求，会包含纯文本摘要。
     • sort（对象，可选）：要排序的字段和方向（例如，{"cited_by_count": "desc"}）。
     • per_page（整数，可选，默认值：25）：每页结果数（最多 200）。
     • cursor（字符串，可选）：分页游标。
   • 返回： 包含 results（作品对象列表）和 meta（分页信息，包括 next_cursor）的对象。

2. get_work_details：

   • 描述： 根据作品 ID（OpenAlex ID URL、DOI URL、PMID URL、MAG ID）检索特定 OpenAlex 作品的详细信息。
   • 参数：
     • work_id（字符串，必填）：作品标识符。
     • select_fields（字符串数组，可选）：要返回的根级字段列表。如果请求，会包含纯文本摘要。
   • 返回： 包含所选字段的作品对象，或错误对象。

3. get_referenced_works：

   • 描述： 检索特定 OpenAlex 作品所引用的 OpenAlex ID 列表（引用其他作品）。注意：此工具目前仅返回 ID 列表。要了解每条引用的更多信息，请使用 get_work_details。
   • 参数：
     • work_id（字符串，必填）：引用其他作品的作品的 OpenAlex ID。
   • 返回： 包含 referenced_work_ids（字符串列表）的对象，或错误对象。

4. get_citing_works：

   • 描述： 检索引用特定 OpenAlex 作品的作品列表（被其他作品引用）。使用游标分页。
   • 参数：
     • work_id（字符串，必填）：被引用作品的 OpenAlex ID。
     • select_fields（字符串数组，可选）：每个引用该作品的作品要返回的根级字段列表。
     • per_page（整数，可选，默认值：25）：每页结果数（最多 200）。
     • cursor（字符串，可选）：分页游标。
   • 返回： 包含 results（引用该作品的作品对象列表）和 meta（分页信息）的对象，或错误对象。

5. get_work_ngrams：

   • 描述： 如果可用，检索特定 OpenAlex 作品全文的 N 元语法（词语邻近信息）。
   • 参数：
     • work_id（字符串，必填）：作品的 OpenAlex ID。
   • 返回： 表示 N 元语法的对象，或错误对象（例如，未找到 N 元语法时）。

注意

由于版权原因，OpenAlex 通常不存储全文。 这也意味着 OpenAlex 搜索功能不会搜索全文，只会搜索标题和摘要。

设置与安装

安装

1. 克隆代码库（可选）：

   git clone <repository-url>
   cd openalex-mcp-server
   

2. 安装依赖项：

   uv venv
   source .venv/bin/activate
   
   uv pip install .
   

   这会安装服务包及其依赖项（mcp[cli]、pyalex）。

3. 运行服务：

   uv --directory /YOUR/INSTALL/DIRECTORY/openalex-mcp-server run server.py
   

配置

• OpenAlex 礼貌池： 若要使用速度更快、更可靠的 OpenAlex 礼貌池，请在运行服务之前或在 MCP 客户端中配置时，将 OPENALEX_EMAIL 环境变量设置为你的电子邮箱地址。

  export OPENALEX_EMAIL="[email protected]"
  

  如果未设置此变量，服务将使用匿名池，其速率限制更严格。

MCP 集成

若要将此服务与 MCP 客户端（例如 Claude VS Code Extension 或 Claude Desktop）配合使用，你需要将其配置添加到客户端的设置文件中。

配置示例（cline_mcp_settings.json 或类似文件）：

{
  "mcpServers": {
    "... other servers ...": {},
    "openalex": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 60,
      "command": "uv",
      "args": [
        "--directory", "/YOUR/INSTALL/DIRECTORY/openalex-mcp-server", "run", "server.py"
      ],
      "env": {
        "OPENALEX_EMAIL": "[email protected]" // Set your email here!
      },
      "transportType": "stdio"
    }
  }
}

• 将 "[email protected]" 替换为你的实际电子邮箱地址。
• 添加配置后，重启 MCP 客户端（例如，重新加载 VS Code 窗口）。

用法

配置并运行服务后（通过 MCP 客户端集成，或为开发而手动运行），你可以在 AI Agent 中使用 use_mcp_tool 命令与之交互。

工具调用示例：

• 搜索 2023 年发表的“machine learning”相关论文：

  <use_mcp_tool>
    <server_name>openalex</server_name>
    <tool_name>search_works</tool_name>
    <arguments>
    {
      "search_query": "machine learning",
      "filters": { "publication_year": 2023 },
      "select_fields": ["id", "doi", "title", "publication_year", "cited_by_count"]
    }
    </arguments>
  </use_mcp_tool>
  

• 获取特定作品的详细信息：

  <use_mcp_tool>
    <server_name>openalex</server_name>
    <tool_name>get_work_details</tool_name>
    <arguments>
    {
      "work_id": "W2741809807",
      "select_fields": ["title", "authorships", "abstract", "open_access"]
    }
    </arguments>
  </use_mcp_tool>
  

• 获取作品的参考文献：

  <use_mcp_tool>
    <server_name>openalex</server_name>
    <tool_name>get_referenced_works</tool_name>
    <arguments>
    {
      "work_id": "W2741809807"
    }
    </arguments>
  </use_mcp_tool>
  

开发

若要在本地运行服务以进行开发和测试：

1. 确保已安装依赖项（参见安装）。
2. 设置 OPENALEX_EMAIL 环境变量。
3. mcp dev server.py

依赖项

• mcp-sdk：用于实现 MCP 服务。
• pyalex：用于与 OpenAlex API 交互。