Scopus MCP Server

一个包装了 Elsevier Scopus API 的 MCP 服务器，使 MCP 客户端（Claude Desktop、Claude Code 或任何其他 MCP 主机）能够搜索和检索已发表的学术文章——适用于基于真实同行评审来源的引文验证和写作风格分析。

工具

所有响应均为结构化 JSON（见下文 响应结构）。当 Scopus API 不可达、被限流或收到无效 ID 时，每个工具都会返回友好的结构化错误而不是抛出异常——参见 错误处理。

在底层，服务器调用两个 Elsevier API：

• Scopus Search API（GET /content/search/scopus）——由 search_scopus 使用。

• Abstract Retrieval API（GET /content/abstract/scopus_id/{id}）——由 get_article_details 和 get_article_abstract 使用，因为 Search API 不能可靠地返回完整摘要、被引次数或关键词。

Related MCP server: MCP-scopus

项目结构

mcp-server/
├── src/
│   ├── index.ts          # stdio entry point (for local MCP clients)
│   ├── httpServer.ts      # Streamable HTTP entry point (for remote deployment)
│   ├── registerTools.ts   # tool definitions, shared by both entry points
│   ├── scopusClient.ts    # Elsevier API client: requests, normalization, error mapping
│   ├── types.ts           # TypeScript types for raw Scopus responses + normalized output
│   └── logger.ts          # structured logger → stderr + logs/scopus-mcp.log
├── test/
│   └── test-connection.ts # standalone connectivity test (bypasses the MCP protocol)
├── logs/                  # log file written here at runtime (gitignored)
├── .env.example
├── package.json
└── tsconfig.json

前提条件

• Node.js 18 或更高版本（使用内置的全局 fetch）。用 node -v 检查。

• Scopus API 密钥。 在 Elsevier Developer Portal 注册一个免费密钥。请注意，Elsevier 会按 IP 范围（机构订阅）或 Institutional Token 限制全文/摘要访问——仅凭密钥即可测试连接性和基本搜索，但某些字段可能会因您的权限而受到限制。

安装

cd mcp-server
npm install
cp .env.example .env

编辑 .env 并设置您的密钥：

SCOPUS_API_KEY=your_real_key_here

SCOPUS_API_KEY 在启动时从环境中读取（src/scopusClient.ts）；它绝不会被硬编码，而且 .env 已被 gitignore 忽略，因此不会被意外提交。

环境变量

先测试连接

在将服务器接入任何 MCP 客户端之前，先验证 Scopus API 密钥和网络路径是否正常：

npm run test:connection

这会运行 test/test-connection.ts，它调用与工具相同的客户端函数——但直接调用，不通过 MCP 协议——针对示例查询 "farmland abandonment Nepal"。您也可以传入自己的查询：

npm run test:connection -- "AUTH(Smith J) AND TITLE(remote sensing)"

它会按顺序遍历所有三个工具（搜索 → 详情 → 第一条结果的摘要），并逐步打印 ✅/❌，同时在 logs/scopus-mcp.log 中记录完整的请求/响应日志（见 日志）。只有当每一步都成功时退出码才为 0。

本地运行（stdio，适用于本地 MCP 客户端）

npm run dev     # runs src/index.ts directly via tsx, no build step
# or
npm run build && npm start   # compiles to dist/ then runs the compiled server

服务器通过 stdio 通信，因此直接在终端中运行它会一直等待 stdin 上的 JSON-RPC——这是预期行为。它应由 MCP 客户端启动。

连接到 Claude Code

claude mcp add scopus --env SCOPUS_API_KEY=your_real_key_here -- node /absolute/path/to/mcp-server/dist/index.js

（先运行 npm run build，确保 dist/index.js 存在），或者将其添加到项目的 .mcp.json：

{
  "mcpServers": {
    "scopus": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": { "SCOPUS_API_KEY": "your_real_key_here" }
    }
  }
}

连接到 Claude Desktop

将相同的配置块添加到 claude_desktop_config.json （Windows 上为 %APPDATA%\Claude\claude_desktop_config.json， macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json），然后重启 Claude Desktop：

{
  "mcpServers": {
    "scopus": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": { "SCOPUS_API_KEY": "your_real_key_here" }
    }
  }
}

响应结构

search_scopus 示例（已截断）：

{
  "query": "farmland abandonment Nepal",
  "totalResults": 42,
  "returnedResults": 10,
  "articles": [
    {
      "scopusId": "85123456789",
      "eid": "2-s2.0-85123456789",
      "title": "Drivers of farmland abandonment in the mid-hills of Nepal",
      "authors": ["Sharma B.", "Poudel K."],
      "publicationYear": 2021,
      "sourceTitle": "Land Use Policy",
      "doi": "10.1016/j.landusepol.2021.105123",
      "doiUrl": "https://doi.org/10.1016/j.landusepol.2021.105123",
      "scopusUrl": "https://www.scopus.com/inward/record.uri?...",
      "citedByCount": 17,
      "abstract": null,
      "documentType": "Article"
    }
  ]
}

get_article_details 在相同字段之外还添加了 keywords、subjectAreas、openAccess 和 aggregationType。get_article_abstract 返回 { scopusId, title, abstract, hasAbstract }。

Scopus 对某条记录没有的字段会以 null 返回（列表字段返回 []，或返回 hasAbstract: false），而不是省略——在断定字段缺失是 bug 之前，请先检查 null/false。

错误处理

每个工具都会在内部捕获错误，并返回 isError: true 及结构化 JSON 正文，而不是让 MCP 连接崩溃：

{
  "error": true,
  "kind": "rate_limited",
  "message": "Scopus API rate limit exceeded (HTTP 429) for search_scopus(...). Retry after 30s.",
  "status": 429,
  "retryAfterSeconds": 30
}

kind 为以下之一：unauthorized（API 密钥错误/缺失）、rate_limited（HTTP 429）、not_found（错误的 Scopus ID / HTTP 404）、bad_request（查询为空、输入格式错误）、network_error（DNS/连接失败）、timeout（超过 SCOPUS_REQUEST_TIMEOUT_MS）或 unknown。搜索成功但没有匹配结果不是错误——它会返回 totalResults: 0 以及一条建议如何扩大查询范围的人类可读 message。

日志

所有 API 调用和响应都会记录日志，便于调试：

• 每个请求在发送前都会记录其 URL（API 密钥已打码）。

• 每个响应都会记录状态码、耗时和 500 字符的正文预览。

• 日志以单行 JSON 的形式写入 stderr（绝不会写入 stdout——在 stdio 传输中，stdout 专用于 MCP 协议），同时也会追加到 logs/scopus-mcp.log。

• 设置 LOG_LEVEL=debug 可获取更多细节，或设置 LOG_LEVEL=error 以减少输出。

部署到远程/无服务器平台（Render、Railway 等）

stdio 传输（src/index.ts）仅适用于能够启动本地进程的 MCP 客户端——它无法通过网络访问。要远程托管此服务器，请改用 Streamable HTTP 入口点：src/httpServer.ts。它在 POST /mcp 上提供相同的三个工具，并增加了一个 GET /healthz 端点用于平台的健康检查。

Render 和 Railway 都不是真正的“无服务器”（没有请求中途的缩容到零冷启动）——二者都是将其作为普通的常驻 Node 进程运行，而这正是 MCP 这类有状态协议所需要的。这里的“无服务器平台”可理解为“托管式 Node 托管”。

Render

1. 将此仓库（或仅 mcp-server/ 文件夹）推送到 GitHub。

2. 在 Render 控制台中：New → Web Service，连接仓库，如果它是更大仓库的子文件夹，则将 root directory 设置为 mcp-server。

3. Build command（构建命令）： npm install && npm run build

4. Start command（启动命令）： npm run start:http

5. 在 Environment（环境变量） 下添加：

   • SCOPUS_API_KEY = 您的密钥（标记为 secret）

   • MCP_HTTP_AUTH_TOKEN = 您生成的一长串随机字符串（例如 openssl rand -hex 32）

   • 可选 MCP_ALLOWED_HOSTS = 您的 Render 主机名，例如 scopus-mcp.onrender.com

6. Render 会自动设置 PORT——httpServer.ts 会读取它，无需任何操作。

7. 部署。健康检查路径：/healthz。

Railway

1. New Project → Deploy from GitHub repo，如有需要将服务根目录设置为 mcp-server。

2. Railway 会自动检测 Node；如果它没有运行正确的命令，请设置：

   • Build command（构建命令）： npm install && npm run build

   • Start command（启动命令）： npm run start:http

3. 在 Variables（变量） 中添加上述 SCOPUS_API_KEY 和 MCP_HTTP_AUTH_TOKEN。

4. Railway 会自动注入 PORT。

5. 部署完成后，您的 MCP 端点为 https://<your-app>.up.railway.app/mcp。

将 MCP 客户端连接到托管的服务器

claude mcp add --transport http scopus https://<your-app>/mcp \
  --header "Authorization: Bearer <your MCP_HTTP_AUTH_TOKEN>"

HTTP 部署的安全说明

• 始终设置 MCP_HTTP_AUTH_TOKEN。 否则，任何拥有 URL 的人都可以调用您的工具并消耗您的 Scopus API 配额——如果未设置，服务器会在启动时记录一条警告。

• 服务器会自动为 localhost/127.0.0.1 启用 DNS 重绑定防护；对于真正的 0.0.0.0 部署，请将 MCP_ALLOWED_HOSTS 设置为您的平台主机名。

• 通过您平台的密钥管理器轮换 SCOPUS_API_KEY 和 MCP_HTTP_AUTH_TOKEN，切勿将其提交到仓库。

• 对于公开部署，建议在 Elsevier 自身按密钥的速率限制之外，再在前面加上平台自身的速率限制/反向代理。

故障排查

许可证

MIT