Scopus MCP Server

Elsevier Scopus API をラップする MCP サーバーで、MCP クライアント（Claude Desktop、Claude Code、その他の MCP ホスト）が査読済みの学術記事を検索・取得できるようにします。実際の査読済みソースに基づいた引用検証や文体分析に役立ちます。

Tools

すべてのレスポンスは構造化された JSON です（下記の レスポンス形式 を参照）。各ツールは、Scopus API が到達不能、レート制限、または不正な ID が指定された場合に例外を投げる代わりに、親しみやすい構造化エラーを返します（エラーハンドリング を参照）。

内部では、サーバーは2つの 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

Project layout

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

Prerequisites

• Node.js 18 以降（組み込みのグローバル fetch を使用）。node -v で確認してください。

• Scopus API キー。 Elsevier Developer Portal で無料キーを登録してください。Elsevier はフルテキスト/抄録へのアクセスを IP 範囲（機関購読）または Institutional Token で制限していることに注意してください。キーだけでも接続テストと基本的な検索には十分ですが、一部のフィールドは権限によって制限される場合があります。

Setup

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 されているため、誤ってコミットされることはありません。

Environment variables

Test connectivity first

サーバーを 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)"

3つのツールすべてを順番に（検索 → 詳細 → 最初の結果の抄録）実行し、各ステップで ✅/❌ を表示します。また、logs/scopus-mcp.log に完全なリクエスト/レスポンスログを出力します（ロギング を参照）。終了コードが 0 になるのは、すべてのステップが成功した場合のみです。

Running locally (stdio, for a local MCP client)

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 クライアントによって起動されることを意図しています。

Connect it to 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" }
    }
  }
}

Connect it to 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" }
    }
  }
}

Response shape

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）として返されます。バグによる欠落と判断する前に、null/false を確認してください。

Error handling

各ツールはエラーを内部でキャッチし、MCP 接続をクラッシュさせる代わりに、構造化された JSON ボディとともに isError: true を返します：

{
  "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 を返します。

Logging

デバッグ用にすべての API 呼び出しとレスポンスがログに記録されます：

• 送信前に、各リクエストの URL（API キーは伏せ字）をログに記録します。

• 各レスポンスのステータスコード、経過時間、500文字のボディプレビューをログに記録します。

• ログは stderr に単一行の JSON として出力されます（stdout は決して使用しません。stdout は stdio トランスポートでの MCP プロトコル用に予約されています）。また、logs/scopus-mcp.log にも追記されます。

• 詳細が必要な場合は LOG_LEVEL=debug を、静かにしたい場合は LOG_LEVEL=error を設定してください。

Deploying to a remote/serverless platform (Render, Railway, etc.)

stdio トランスポート（src/index.ts）は、ローカルプロセスを起動できる MCP クライアントでのみ機能します。ネットワーク経由では到達できません。このサーバーをリモートでホストするには、代わりに Streamable HTTP エントリポイント（src/httpServer.ts）を使用してください。同じ3つのツールを 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 = あなたのキー（シークレットとしてマーク）

   • 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 になります。

Connecting an MCP client to the hosted server

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

Security notes for HTTP deployment

• 常に 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 のキーごとのレート制限に加えて、プラットフォーム独自のレート制限/リバースプロキシを前面に配置することを検討してください。

Troubleshooting

License

MIT