Uniprot Mcp

uniprot-mcp

GitHub リポジトリ：fzlzjerry/uniprot-mcp · PyPI パッケージとコマンド：uniprotkb-mcp （Python のインポートパッケージは uniprot_mcp です）。

UniProt REST APIをstdio経由でLLMクライアント（Claude Code、Claude Desktopなど）に提供する、プロダクション品質のMCP サーバーです。FastMCPで構築し、uvで管理しています。

ツールはデフォルトでコンパクトかつトークン効率の高い要約を返し、要求された場合にのみ完全なペイロードを返します。また、堅牢なエラー処理と、モデルが有効なクエリを作成できるようにするUniProtクエリのチートシートを内蔵しています。

クイックスタート

PyPIで公開されています。クローンもインストールも不要です：

uvx uniprotkb-mcp

次に、MCPクライアントからこのサーバーを指定します（設定の詳細は以下を参照）：

{
  "mcpServers": {
    "uniprot": {
      "command": "uvx",
      "args": ["uniprotkb-mcp"],
      "env": { "UNIPROT_MCP_CONTACT": "[email protected]" }
    }
  }
}

ツール

ツール	内容
search_uniprotkb	ネイティブのクエリ構文でUniProtKBを検索します。reviewed／organism_idフィルターは自動的に追加されます。要約、FASTA、またはTSV形式で出力します。
get_entry	1件のエントリーを精選したダイジェスト（機能、名称、生物種、長さ、細胞内局在、ファミリー／ドメイン、主な特徴、PTM、キーワード、PDB／AlphaFold／Ensembl／RefSeq／InterPro／GOのクロスリファレンス）またはjson／fasta／txt／gff形式で取得します。
get_fasta	1件または複数のアクセッションについて、FASTAをそのまま取得します。
map_ids	UniProtの非同期IDマッピングを使ってデータベース間のIDを変換します（例：RefSeq_Protein→UniProtKB、UniProtKB_AC-ID→PDB）。マッピングされたペアとマッピングされなかったIDを返し、データベースのペアを最新の設定に照らして検証します。
get_taxonomy	生物種名または分類群IDを解決し、分類群ID、名称、階級、系統を返します。「human」をorganism_id:9606に変換できます。
search_uniref	UniRef100／90／50の配列類似性クラスターを検索します。
search_proteomes	プロテオーム（生物種全体のタンパク質セット）を検索します。参照プロテオームのフィルターに対応しています。

さらに、UniProtKBのクエリ構文（gene:、organism_id:、reviewed:true、length:[X TO Y]、keyword:、ec:、ブール演算子のAND/OR/NOTなど）を説明するMCPリソースresource://uniprot/query-cheatsheetも利用できます。

要件

• Python ≥ 3.10（リポジトリでは.python-versionにより3.13を指定しています）
• uv

インストール

git clone https://github.com/fzlzjerry/uniprot-mcp
cd uniprot-mcp
uv sync                 # creates .venv and installs fastmcp + httpx

実行

# stdio server (what MCP clients launch):
uv run uniprotkb-mcp

UniProtでは、APIクライアントに連絡先住所を名乗るよう求めています。UNIPROT_MCP_CONTACT環境変数で設定してください（User-Agentに使用されます）。設定しない場合は、プレースホルダーが使用されます。

UNIPROT_MCP_CONTACT="[email protected]" uv run uniprotkb-mcp

uvxで実行（クローン／同期不要）

uvx（別名：uv tool run）は、一時的な環境にコンソールスクリプトを取得、ビルドして実行します。事前のインストールは不要です。利用できるソースを選択してください：

# From PyPI (published):
uvx uniprotkb-mcp

# From a Git repo (note: repo is uniprot-mcp, command is uniprotkb-mcp):
uvx --from git+https://github.com/fzlzjerry/uniprot-mcp uniprotkb-mcp

# From a local checkout (this directory):
uvx --from /ABSOLUTE/PATH/TO/uniprot-mcp uniprotkb-mcp

# From a built wheel:
uvx --from ./dist/uniprotkb_mcp-0.1.0-py3-none-any.whl uniprotkb-mcp

uvx [email protected]でバージョンを固定するか、uvx --refresh --from <source> uniprotkb-mcpでキャッシュ済みビルドを強制的に更新できます。

Claude Desktop に登録する

claude_desktop_config.json （macOS：~/Library/Application Support/Claude/claude_desktop_config.json、 Windows：%APPDATA%\Claude\claude_desktop_config.json）を編集して、次を追加します。

{
  "mcpServers": {
    "uniprot": {
      "command": "uvx",
      "args": ["uniprotkb-mcp"],
      "env": { "UNIPROT_MCP_CONTACT": "[email protected]" }
    }
  }
}

これにより、公開済みのパッケージを PyPI から直接実行します。代わりに未リリースのコードを実行するには、ソースを追加します。"args": ["--from", "git+https://github.com/fzlzjerry/uniprot-mcp", "uniprotkb-mcp"] （git）または "args": ["--from", "/ABSOLUTE/PATH/TO/uniprot-mcp", "uniprotkb-mcp"] （ローカルチェックアウト）を指定します。Claude Desktop が参照する PATH に uvx があることを確認してください（uv に同梱されています。必要であれば、~/.local/bin/uvx のように uvx の絶対パスを指定してください）。 Claude Desktop を再起動すると、uniprot ツールが表示されます。

uvx ではなくクローンしたチェックアウトを使いたいですか？次を使用します。 "command": "uv", "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/uniprot-mcp", "uniprotkb-mcp"]。

Claude Code に登録する

プロジェクトのルートに .mcp.json を置き、プロジェクト単位で設定します（同じ形式です）。

{
  "mcpServers": {
    "uniprot": {
      "command": "uvx",
      "args": ["uniprotkb-mcp"],
      "env": { "UNIPROT_MCP_CONTACT": "[email protected]" }
    }
  }
}

または、CLI から設定します。

# via uvx (published / git / local source):
claude mcp add uniprot -e [email protected] -- uvx uniprotkb-mcp

# via a local checkout with uv:
claude mcp add uniprot -e [email protected] \
  -- uv run --directory /ABSOLUTE/PATH/TO/uniprot-mcp uniprotkb-mcp

スモークテスト

すべてのツールを稼働中の API に対して実行し、出力を表示します。

UNIPROT_MCP_CONTACT="[email protected]" uv run python -m tests.smoke

開発

開発、テスト、CI、リリースプロセス（CI による PyPI Trusted Publishing — トークン不要）については、CONTRIBUTING.md に記載されています。 要約：uv sync を実行し、続いて uv run python -m tests.check_structure（オフライン）と uv run python -m tests.smoke（稼働中の API）を実行します。

設計メモ

• 共有の httpx.AsyncClient を単一使用し、連絡先を含む説明的な User-Agent を設定します。
• 429（Retry-After を尊重）と 5xx ではリトライ／バックオフを行います。400 では UniProt 独自のエラーメッセージを表示します。クライアントに生のトレースバックが渡らないよう、エラーは ToolError として発生させます。
• ページネーションには Link ヘッダー／x-total-results を使用します。結果件数には上限（≤ 500）を設け、常に合計件数を報告するため、絞り込みやページ分割が可能です。
• ID マッピングは実際の非同期フローに従います。POST /idmapping/run → /idmapping/status/{job} をポーリング（303 と Location は完了を示します）→ 結果を取得します。対象データベースに応じて、拡張された UniProtKB 結果エンドポイントと単純なペア用エンドポイントを自動で選択します。

プロジェクト構成

src/uniprot_mcp/
  server.py       # FastMCP instance, the 7 tools, cheat-sheet resource, main()
  client.py       # shared AsyncClient, retry/backoff, error mapping, header parsing
  idmapping.py    # async run/poll/results flow with target-aware routing
  config.py       # cached idmapping db config + from/to validation
  formatting.py   # JSON -> compact summary digests
  cheatsheet.py   # UniProt query cheat-sheet
tests/smoke.py    # live-API smoke test