PubTator MCP Server

PubTator MCP Server

🔍 PubTator3 を基盤とする生物医学文献のアノテーションおよび関係マイニングサーバーです。MCP インターフェースを通じて、便利にアクセスできます。

PubTator MCP Server は、Model Context Protocol（MCP）を通じて、PubTator3 の生物医学文献アノテーションシステムへのアクセスを AI アシスタントに提供します。AI モデルを使って、科学文献をプログラムから検索し、アノテーション情報を取得して、エンティティ間の関係を分析できます。

🤝 貢献 • 📝 問題を報告

✨ 主な機能

• 🔎 文献アノテーションのエクスポート：PubTator のアノテーション結果を複数の形式でエクスポートできます ✅
• 🚀 エンティティ ID の検索：フリーテキストから生物学的概念の標準識別子を検索できます ✅
• 📊 関係マイニング：エンティティ間の生物医学的関係を発見できます ✅
• 📄 文献検索：キーワードやエンティティ ID で文献を検索できます ✅
• 🧠 バッチ処理：検索結果からアノテーション情報を一括エクスポートできます ✅

🚀 クイックスタート

要件

• Python 3.10+
• FastMCP ライブラリ

インストール

Smithery 経由

Smithery を使って PubTator Server を自動インストールします。

Claude

npx -y @smithery/cli@latest install @JackKuo666/pubtator-mcp-server --client claude --config "{}"

Cursor

Settings → Cursor Settings → MCP → Add new server に貼り付けます。

• Mac/Linux

npx -y @smithery/cli@latest run @JackKuo666/pubtator-mcp-server --client cursor --config "{}" 

Windsurf

npx -y @smithery/cli@latest install @JackKuo666/pubtator-mcp-server --client windsurf --config "{}"

CLine

npx -y @smithery/cli@latest install @JackKuo666/pubtator-mcp-server --client cline --config "{}"

手動インストール

1. リポジトリをクローンします。

   git clone https://github.com/JackKuo666/PubTator-MCP-Server.git
   cd PubTator-MCP-Server
   

2. 依存関係をインストールします。

   pip install -r requirements.txt
   

📊 使用方法

サーバーを直接実行する

MCP サーバーを起動します。

python pubtator_server.py

サーバーは stdio と TCP の両方のトランスポートに対応しています。デフォルトでは TCP トランスポートを使用します。次の環境変数を設定できます。

• MCP_TRANSPORT：TCP トランスポートの場合は「tcp」、stdio トランスポートの場合は「stdio」に設定します（デフォルトは「tcp」）。
• MCP_HOST：バインドするホスト（デフォルトは「0.0.0.0」）。
• MCP_PORT：リッスンするポート（デフォルトは 8080）。

カスタム設定でサーバーを起動する例：

MCP_TRANSPORT=tcp MCP_HOST=127.0.0.1 MCP_PORT=8888 python pubtator_server.py

サーバーは遅延初期化と適切なエラー処理を実装しています。シャットダウンシグナル（SIGINT と SIGTERM）を適切に処理し、起動時または動作中に発生したエラーをログに記録します。

Docker を使用する

簡単にデプロイできるよう、Dockerfile を用意しています。Docker コンテナを使用するには、次の手順に従ってください。

1. Docker イメージをビルドします。

   docker build -t pubtator-mcp-server .
   

2. Docker コンテナを実行します。

   docker run -p 8080:8080 pubtator-mcp-server
   

これにより、Docker コンテナ内で PubTator MCP サーバーが起動し、ポート 8080 で公開されます。

トラブルシューティング

サーバーの起動時に問題が発生した場合：

1. コンソール出力でエラーメッセージを確認します。
2. 必要な依存関係がすべてインストールされていることを確認します（「要件」セクションを参照）。
3. 環境変数が正しく設定されていることを確認します。
4. サーバーが起動しない場合は、詳細度を上げて実行してみてください。

python -v pubtator_server.py

これにより、問題の原因を特定するのに役立つ詳細なログ情報が出力されます。

Docker を使用している場合は、次のコマンドでログを確認できます。

docker logs <container_id>

設定

Claude Desktop の設定

claude_desktop_config.json に追加します。

（Mac OS）

{
  "mcpServers": {
    "pubtator": {
      "command": "python",
      "args": ["-m", "pubtator-mcp-server"]
      }
  }
}

（Windows）

{
  "mcpServers": {
    "pubtator": {
      "command": "C:\\Users\\YOUR\\PATH\\miniconda3\\envs\\mcp_server\\python.exe",
      "args": [
        "D:\\code\\YOUR\\PATH\\PubTator-MCP-Server\\pubtator_server.py"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

CLine の設定

{
  "mcpServers": {
    "pubtator": {
      "command": "bash",
      "args": [
        "-c",
        "source /home/YOUR/PATH/mcp-server-pubtator/.venv/bin/activate && python /home/YOUR/PATH/pubtator_server.py"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

TCP トランスポートを使用するには、次のように設定を変更します。

{
  "mcpServers": {
    "pubtator": {
      "command": "bash",
      "args": [
        "-c",
        "source /home/YOUR/PATH/mcp-server-pubtator/.venv/bin/activate && python /home/YOUR/PATH/pubtator_server.py"
      ],
      "env": {
        "MCP_TRANSPORT": "tcp",
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "8888"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

🛠 API 機能

PubTator MCP Server は、次の主な機能を提供します。

1. 文献のエクスポート（export_publications）

指定した PMID の文献について、PubTator のアノテーション結果をエクスポートします。

result = await export_publications(
    ids=["32133824", "34170578"],
    id_type="pmid",
    format="biocjson",  # Supported: pubtator, biocxml, biocjson
    full_text=False     # Whether to include full text
)

2. エンティティ ID の検索（find_entity_id）

フリーテキストから生物学的概念の標準識別子を検索します。

result = await find_entity_id(
    query="COVID-19",
    concept="disease",  # Optional: gene, disease, chemical, species, mutation
    limit=5             # Optional: limit number of results
)

3. 関連エンティティの検索（find_related_entities）

指定したエンティティに関連する他のエンティティを検索します。

result = await find_related_entities(
    entity_id="@DISEASE_COVID_19",
    relation_type="treat",    # Optional: treat, cause, interact, etc.
    target_entity_type="chemical",  # Optional: gene, disease, chemical
    max_results=5       # Optional: limit number of results
)

4. 文献検索（search_pubtator）

PubTator データベースを検索します。

results = await search_pubtator(
    query="COVID-19",
    max_pages=1     # Optional: maximum number of pages to retrieve
)

5. 一括エクスポート（batch_export_from_search）

検索して文献のアノテーションを一括エクスポートします：

results = await batch_export_from_search(
    query="COVID-19",
    format="biocjson",
    max_pages=1,
    full_text=False,
    batch_size=5
)

注：実際の関数呼び出しは、実装によって異なる場合があります。これらの例は最近のテストに基づいており、正確な API に合わせて調整が必要になる場合があります。

⚠️ 使用上の制限

• API リクエストのレート制限：最大 1 秒あたり 3 リクエスト
• 一括エクスポート時は、リクエストがタイムアウトしないよう、適切な batch_size を使用してください
• 関係性を問い合わせる場合、エンティティ ID は「@」で始める必要があります（例：「@DISEASE_COVID-19」）

📄 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。

⚠️ 免責事項

このツールは研究目的のみで使用してください。PubTator の利用規約を遵守し、責任を持ってこのツールを使用してください。