biothings-mcp

biothings-mcp

Biothings.io 用の MCP（Model Context Protocol）サーバーです。

このサーバーは、Biomedical データにアクセスして操作するための標準化されたインターフェースを提供する、BioThings 用の Model Context Protocol（MCP）を実装しています。MCP により、AI アシスタントやエージェントは、信頼できるデータソースへの構造化インターフェースを通じて、専門的な Biomedical の知識にアクセスできます。対応する BioThings データソースは次のとおりです。

• mygene.info — 遺伝子アノテーションおよびクエリサービス
• myvariant.info — バリアントアノテーションおよびクエリサービス
• mychem.info — 化合物アノテーションおよびクエリサービス

Model Context Protocol とは何か、またより効率的に使用する方法について詳しく知りたい場合は、DeepLearning AI Course を受講するか、YouTube で MCP の動画を検索してください。

MCP（Model Context Protocol）について

MCP は、AI システムと専門分野の知識の間をつなぐプロトコルです。次の機能を提供します。

• 構造化アクセス：信頼できる Biomedical データソースへの直接接続
• 自然言語クエリ：専門データベースとのやり取りを簡素化
• 型安全性：biothings-typed-client による強力な型付けと検証
• AI 統合：AI アシスタントやエージェントとのシームレスな統合

利用可能な API インターフェース

このサーバーは、biothings-typed-client ライブラリを活用して、さまざまな BioThings データ型に対応する専用の API インターフェースを提供します。これらのインターフェースは、次のツールハンドラーを使用して実装されています。

• 遺伝子インターフェース：GeneTools（GeneClientAsync をラップ）
• バリアントインターフェース：VariantTools（VariantClientAsync をラップ）
• 化学物質インターフェース：ChemTools（ChemClientAsync をラップ）
• 分類群インターフェース：TaxonTools（TaxonClientAsync をラップ）
• ダウンロードインターフェース：DownloadTools（ファイルダウンロードおよび配列解析機能を提供）

ローカルファイル保存機能

このサーバーには、DownloadTools インターフェースによるローカルファイル保存機能が含まれています。次の機能を提供します。

ダウンロードツール

• download_entrez_data：NCBI Entrez データベースからデータをダウンロード（コンテンツを文字列として返します）
• download_entrez_data_local：NCBI Entrez データベースからデータをダウンロードしてローカルファイルに保存

出力ディレクトリの管理

• デフォルトの場所：ファイルは現在の作業ディレクトリ内の biothings_output/ ディレクトリに保存されます
• カスタムの場所：--output-dir パラメーターを使用して、カスタム出力ディレクトリを指定します
• 自動作成：出力ディレクトリが存在しない場合、自動的に作成されます
• 一意のファイル名：競合を避けるため、自動生成されるファイル名には UUID プレフィックスが含まれます

対応するファイル形式

• FASTA：配列データ用の .fasta 拡張子
• GenBank：GenBank 形式データ用の .gb 拡張子
• アラインメント：アラインメント結果用の .aln 拡張子
• JSON：構造化データ用の .json 拡張子
• テキスト：一般的なテキストデータ用の .txt 拡張子

クイックスタート

uv のインストール

# Download and install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version
uvx --version

uvx は、必要に応じて Python パッケージをインストールして実行できる、とても便利なツールです。

uvx を使用した実行

リポジトリをクローンせずに、uvx を使用して biothings-mcp サーバーを直接実行できます。

STDIO モード（ファイルを保存する場合に便利な、stdio を必要とする MCP クライアント向け）

# Run the server in STDIO mode (default mode)
uvx biothings-mcp

# Or explicitly specify stdio mode
uvx --from biothings-mcp stdio

# With custom output directory
uvx --from biothings-mcp stdio --output-dir ./my_data

HTTP Streamable モード（Web サーバー）

# Run the server in streamable HTTP mode on default port (3001)
uvx --from biothings-mcp server run

# Run on a custom port
uvx --from biothings-mcp server run --port 8000

# Run on custom host and port
uvx --from biothings-mcp server run --host 0.0.0.0 --port 8000

# With custom output directory
uvx --from biothings-mcp server run --output-dir ./my_data

SSE モード（Server-Sent Events）

# Run the server in SSE mode on default port (3001)
uvx --from biothings-mcp sse

# Run on a custom port
uvx --from biothings-mcp sse --port 8000

HTTP ストリーム可能モードでは、http://localhost:3001/mcp（ドキュメントは http://localhost:3001/docs）でアクセスできるウェブサーバーが起動します。STDIO モードは標準入力／出力を介して通信する MCP クライアント向けに設計されています。一方、SSE モードではリアルタイム通信に Server-Sent Events を使用します。

ご利用の（Anthropic Claude Desktop、Cursor、Windsurf など）の設定

プロキシを使用する stdio 設定を用意しています（実行には npx が必要な場合があります）。

• mcp-config-remote.json - リモート設定用
• mcp-config-stdio.json - MCP クライアント向けの localhost 用 stdio 設定（非対応の場合は利用できません）

Biothings MCP サーバーの調査

MCP が提供するメソッドを調べる場合は、npx を使用してください（nodejs と npm のインストールが必要な場合があります）。

MCP Inspector で MCP のセットアップをテストします。

ローカルの streamable-http サーバーを調べる場合は、次を使用します。

npx @modelcontextprotocol/inspector --config mcp-config.json --server biothings-mcp

リモートサーバーの場合は、-remote サフィックスを追加してください。

ローカルの stdio サーバーを調べる場合は、次を使用してください。

npx @modelcontextprotocol/inspector --config mcp-config-stdio.json --server biothings-mcp

Inspector を手動で起動し、インターフェースにサーバーのパラメーターを入力することもできます。

npx @modelcontextprotocol/inspector

その後、http://127.0.0.1:6274 の MCP Inspector でメソッドを確認できます。

リポジトリのセットアップ

# Clone the repository
git clone https://github.com/longevity-genie/biothings-mcp.git
cd biothings-mcp
uv sync

MCP サーバーの実行

リポジトリをすでにクローンしている場合は、uv でサーバーを実行できます。

# Start the MCP server in HTTP streamable mode (default port 3001)
uv run server run

# Run in STDIO mode
uv run stdio

# Run in SSE mode
uv run sse

# Run with custom port
uv run server run --port 8000

# Run with custom output directory
uv run server run --output-dir ./my_data

AI システムとの統合

このサーバーを MCP 対応 AI クライアントと統合するには、このリポジトリに用意されている、事前設定済みの JSON ファイルのいずれかを使用できます。

• ローカルで実行中のサーバーに接続する場合： mcp-config.json を使用します。まず、uv run server（MCP サーバーの実行を参照）または docker-compose up（Docker デプロイを参照）でサーバーが起動していることを確認してください。
• 公開ホスト型サーバーに接続する場合： mcp-config-remote.json を使用します。これは https://biothings.longevity-genie.info/mcp に接続するため、ローカルで何かを実行する必要はありません。

AI クライアント（Cursor、Windserve、ClaudeDesktop、Copilot を搭載した VS Code、またはその他など）に、適切な設定ファイルを使用するよう指定してください。

設定後、Cursor などの MCP クライアントでは、ツールが次のように表示されます。

既知の問題

このライブラリはベータ品質です。現在の主な問題は、LLM が適切な遺伝子および遺伝子変異のシンボルを指定できないことが多い点です。コメントを拡充し、エンティティ解決のためのメソッドを追加することで、この問題の軽減を予定しています。

テストと検証

API エンドポイントのテストを実行します。

uv run pytest -vvv -s

ローカルにビルドした MCP サーバーでも、uvx の場合と同じ方法で MCP Inspector を使用できます。

注：MCP Inspector の使用は任意です。Cursor、Windsurv など、ほとんどの MCP クライアントでは、設定後にこのサーバーで利用可能なツールが自動的に表示されます。ただし、Inspector は詳細なテストや調査に役立ちます。

npx で Inspector を使用する場合は、Node.js と npm がインストールされていることを確認してください。Node.js のバージョン管理には、nvm（Node Version Manager）の使用を推奨します。

ウェブインターフェースが開き、利用可能なすべてのツールを調査し、テストできます。

ドキュメント

MCP プロトコルとその実装に関する詳細なドキュメントは、以下を参照してください。

• MCP プロトコルのドキュメント
• biothings-typed-client のドキュメント
• FastAPI-MCP のドキュメント

ライセンス

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

謝辞

• REST API とオリジナルのクライアントライブラリを提供している BioThings

• プロトコル仕様を提供している MCP Protocol

• データ検証フレームワークを提供している Pydantic

• MCP サーバーの実装を提供している FastAPI-MCP

• このプロジェクトは、健康、遺伝学、長寿研究向けのオープンソースの AI アシスタントとライブラリを開発する Longevity Genie 組織の一部です。

以下の団体から支援を受けています。

HEALES - 健康長寿延伸協会

および

IBIMA - 医療・加齢研究における生物統計学・情報学研究所