setup-tooluniverse

ToolUniverse のセットアップ

ToolUniverse のセットアップをユーザーに順を追って案内します。

エージェントの動作

• ユーザーの最初のメッセージから言語を判定します。その言語で応答し、コマンドと URL は英語のままにします。
• 一度に 1 ステップずつ進めます。続行する前に確認します。
• 選択肢を提示するには AskQuestion を使います。
• わかりやすい言葉で簡潔に説明します。小さな進展も称えます。
• 問題が起きた場合は、先にトラブルシューティングを手伝います。

内部メモ（表示しない）

ToolUniverse には 2,700 以上のツールがあります。tooluniverse コマンドはコンパクトモードを自動的に有効にし、5 つのコア MCP ツール（list_tools、grep_tools、get_tool_info、execute_tool、find_tools）のみを公開しながら、execute_tool 経由ですべてのツールを引き続き利用できるようにします。

ToolUniverse とは？

必ず最初に、わかりやすい言葉で説明してください。

ToolUniverse は、2,000 以上の科学データベース（PubMed、UniProt、ChEMBL、FAERS、ClinicalTrials.gov など）に接続する、無料のオープンソースソフトウェアです。個別のウェブサイトを訪れる代わりに、1 か所から検索できます。科学データベース用の万能リモコンのようなものです。

AI アシスタントを使う理由は？ AI が質問を読み取り、検索するデータベースを判断してクエリを実行し、結果を要約します。質問するだけで利用できます。

ステップ 1：使い方を選ぶ

AskQuestion を使って、次の選択肢を提示します。

モード	内容	対象
チャットモード	AI アシスタントに質問します。コーディングは不要です。	ほとんどの研究者。
コマンドライン	ターミナルで短いコマンドを入力します。	手早く試したい方。ターミナルに慣れている方。
Python コード	自動化パイプライン用のスクリプトを作成します。	プログラマー。

選択肢：「質問したい」→ チャットモード｜「手早く試す」→ CLI｜「Python を書く」→ SDK｜「わからない」→ チャットモードを推奨

チャットモードの場合、使用するアプリを尋ねます（AskQuestion）：Cursor、Claude Desktop、VS Code/Copilot、Windsurf、Claude Code、Gemini CLI、Codex、Cline/Trae/Antigravity/OpenCode。「どれも持っていない」→ Claude Desktop を推奨します。

ステップ 2：uv をインストールする

前提条件は uv のみです（それ以外はすべて自動的に管理します）。

ターミナルの開き方（必要な場合）：Mac：Cmd+Space →「Terminal」→ Enter。Windows：Win キー →「PowerShell」→ Enter。

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

（これは uv という小型のパッケージマネージャーをダウンロードしてインストールする、安全で標準的なコマンドです。Python 開発者に広く使われています。完了したら、ターミナルを閉じて再度開いてください。）

確認：uv --version

CLI のセットアップ

ステップ 2 が完了していることを確認してから、次を試します。

uvx --from tooluniverse tu status              # How many tools?
uvx --from tooluniverse tu find 'drug safety'  # Search by topic
uvx --from tooluniverse tu info FAERS_count_death_related_by_drug  # See params
uvx --from tooluniverse tu run FAERS_count_death_related_by_drug '{"medicinalproduct": "metformin"}'

初回は約 30 秒かかります（パッケージをダウンロードするため）。2 回目以降はすぐに実行できます。ショートカット：uv tool install tooluniverse を実行すれば、以降は tu だけで使えます。

CLI のすべてのサブコマンド

コマンド	内容	例
tu status	ツール数と主要カテゴリを表示	tu status
tu list	ツールの一覧を表示（モード：names、categories、basic、by_category、summary、custom）	tu list --mode basic --limit 20
tu find	自然言語で検索（キーワードのスコアリングを使用。API キーは不要）	tu find 'protein structure analysis'
tu grep	テキスト／正規表現パターンで検索	tu grep '^UniProt' --mode regex
tu info	ツールのパラメーターとスキーマを表示	tu info PubMed_search_articles
tu run	ツールを実行	tu run PubMed_search_articles '{"query": "CRISPR"}'
tu test	サンプル入力でツールをテスト	tu test UniProt_get_entry_by_accession
tu build	Coding API 用の型付き Python ラッパーを生成（内部の遅延読み込みレジストリもその場で再生成します。--output の影響は受けません）	tu build --output ./my_tools
tu serve	MCP stdio サーバーを起動（uvx tooluniverse と同じ）	tu serve

出力フラグ（build／serve を除くほとんどのコマンド）：--json（整形表示）または --raw（コンパクト表示、パイプでの使用に適しています）。

ステップ 3（API キー）に進みます。

SDK のセットアップ

まず uv をインストールしてください（手順 2）。システムの pip は使用しないでください。 現行の Mac （Homebrew Python 3.13/3.14）では、pip install tooluniverse を実行すると error: externally-managed-environment（PEP 668）で停止し、python3 -m venv は ensurepip で失敗する場合があります。uv は独自の Python をダウンロードして管理するため、 どちらの問題も回避できます。

uv venv --python 3.12          # own Python + virtualenv, ignores system pip
source .venv/bin/activate      # Windows: .venv\Scripts\activate
uv pip install tooluniverse

uv pip install には有効な仮想環境が必要です。先に uv venv を実行するか、 tu コマンドのみが必要な場合は uv tool install tooluniverse を使用してください。

詳しいパターンについては、tooluniverse-sdk スキルを呼び出してください。

オプションの追加機能：基本のインストールでは API／データベースツールを利用できます。ローカルの ML、 ケモインフォマティクス、プロット用ツールには追加機能が必要です。uv pip install 'tooluniverse[ml]'、[visualization]、[bioinformatics]、または [all] を実行してください。 不足しているグループを確認するには、tooluniverse-doctor を実行してください。 [all] には singlecell、smolagents、client、build は含まれないため、 これらは個別にインストールしてください。

コーディング API — 3 つの呼び出しパターン

パターン 1：直接インポート（型付き、自動補完あり）：

from tooluniverse.tools import UniProt_get_entry_by_accession
result = UniProt_get_entry_by_accession(accession="P12345")

パターン 2：属性アクセス（ツールごとのインポートは不要）：

from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()
result = tu.tools.UniProt_get_entry_by_accession(accession="P12345")

パターン 3：JSON ベース（動的、パイプライン向け）：

result = tu.run({"name": "UniProt_get_entry_by_accession", "arguments": {"accession": "P12345"}})

型付きラッパーを生成するには、tu build を実行してください（自動補完に対応した、インポート可能な Python モジュールが作成されます）。

エージェント型ツールとコード実行ツール

ToolUniverse には、23 個の AI 搭載エージェント型ツール（ScientificTextSummarizer、HypothesisGenerator、ExperimentalDesignScorer、査読ツールなど）と、2 個のコード実行ツール（python_code_executor、python_script_runner）も含まれています。これらは、ほかのツールと同様に tu.run() または execute_tool() 経由で呼び出します。エージェント型ツールには LLM の API キー（例：OPENAI_API_KEY）が必要です。

続けて手順 3（API キー）に進んでください。

MCP のセットアップ（チャットモード）

まず、手間のかからない 2 つの方法を提示してください。 JSON を手動で編集するのは推奨方法ではなく、最後の手段です。入力するコンマを間違えることが、セットアップ失敗の最も一般的な原因です。以下のどちらの方法も適さない場合に限り、手動の方法を案内してください。

方法 A — AI エージェントに任せる。 すでに何らかのエージェント（Claude、 Cursor、Copilot、Gemini、Codex など）を使っている場合は、次の内容を貼り付けることができます。

Read https://aiscientist.tools/setup.md and set up ToolUniverse for me.

エージェントが設定、キー、スキル、検証を処理します。ターミナルも JSON も不要です。

方法 B — Claude Code または Codex のユーザー向け：設定ファイル不要のワンライナー。

Claude Code：

claude plugin marketplace add mims-harvard/ToolUniverse
claude plugin install tooluniverse@tooluniverse

今後のリリースを手動の claude plugin update なしで適用できるように、「自動更新を有効にする」の手順を tooluniverse-claude-code-plugin スキルで確認してください。

Codex：

codex plugin marketplace add mims-harvard/ToolUniverse
codex plugin add tooluniverse -m tooluniverse

検証、更新、トラブルシューティングについては、tooluniverse-codex-plugin スキルを確認してください。

どちらの方法でも、MCP サーバーと 180 以上のスキルが一度にインストールされます。Google Antigravity ユーザーは、代わりに tooluniverse-antigravity-plugin スキルを確認してください。インストール 手順が異なります（マーケットプレイスへの追加ではなく、agy plugin install を使用します）。

手動設定（代替手段）

ステップ 2 が完了していることを確認します（uv --version が動作すること）。

設定ファイルについて（ユーザーが詳しくなさそうな場合）：設定ファイルは、アプリの環境設定リストのように、設定を保存するプレーンテキストファイルです。形式を理解する必要はありません。以下に示す内容をそのまま貼り付けてください。ほとんどのアプリには、ファイルを開く設定ボタンがあります（表を参照）。ファイルが空の場合は、ブロック全体を貼り付けます。すでに内容がある場合は、エージェントがマージを支援します。

デフォルト設定（ほとんどのクライアントで共通）：

{
  "mcpServers": {
    "tooluniverse": {
      "command": "uvx",
      "args": ["tooluniverse"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

安全に貼り付ける。 ブロック全体をコピーしてください。手入力しないでください。ファイルにすでに mcpServers ブロックがある場合は、その中に "tooluniverse": { ... } エントリだけを追加し、直前のエントリの後にカンマを付けます。ファイルが空の場合は、ブロック全体を貼り付けます。アプリを再起動する前に、次のコマンドで検証してください：

python3 -m json.tool < "<path-to-config>" > /dev/null && echo "JSON OK"

最後のエントリの後にカンマがある場合や、エントリ間にカンマがない場合は、「MCP サーバーが起動しない」原因としてよく見られます。

args — ["tooluniverse"] と ["--refresh", "tooluniverse"] の違い：通常の設定がデフォルトで、uv のキャッシュから高速に起動しますが、uv cache clean tooluniverse を実行するまで古いバージョンがキャッシュされたままになることがあります。--refresh を追加すると、起動のたびに PyPI で最新バージョンを確認します。常に最新になりますが、起動に数秒余計にかかります。ユーザーが自動更新を特に希望している場合を除き、通常の設定を使用してください。

設定ファイルの場所：

クライアント	ファイル	アクセス方法
Cursor	~/.cursor/mcp.json	Settings → MCP → Add new global MCP server
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	Settings → Developer → Edit Config
Claude Code	~/.claude.json or .mcp.json	claude mcp add または直接編集（あるいはプラグインを使用。上記を参照）
Windsurf	~/.codeium/windsurf/mcp_config.json	MCP ハンマーアイコン → Configure
Cline	cline_mcp_settings.json	Cline パネル → MCP Servers → Configure
Gemini CLI	~/.gemini/settings.json	gemini mcp add または直接編集
Trae	.trae/mcp.json	Ctrl+U → AI Management → MCP → Configure

形式が異なる場合：VS Code は "servers" キーと "type": "stdio" を使用します。Codex は TOML を使用します。OpenCode は "mcp" キーを使用します。詳細はreferences/mcp-configs.mdを参照してください。

ステップ 3（API キー）に進みます。

ステップ 3：API キー

多くのツールはキーなしで動作しますが、キーを設定すると強力な機能を利用できるものもあります。まず研究分野を確認してください（AskQuestion）：

• 文献／創薬／タンパク質構造／ゲノミクス／希少疾患／酵素学／特許検索／AI 分析／すべて／スキップ

関心に応じて推奨キーを案内します（最初は 2～4 個）。1 つずつ進めます。キーで利用できる機能を説明し、登録リンクを案内して、キーを受け取ったら設定に追加します。

ティア 1（基本 — ほとんどのユーザーに推奨）：

キー	利用できる機能	無料？	登録先
NCBI_API_KEY	PubMed（レート制限が 3→10/秒）	はい	https://account.ncbi.nlm.nih.gov/settings/
NVIDIA_API_KEY	16 個のツール：AlphaFold2、ドッキング、ゲノミクス	はい	https://build.nvidia.com
BIOGRID_API_KEY	タンパク質相互作用のクエリ	はい	https://webservice.thebiogrid.org/
FDA_API_KEY	FDA の有害事象、医薬品ラベル（レートが 240→1000/分）	はい	https://open.fda.gov/apis/authentication/

ティア 2（専門分野 — 関心に応じて）：

キー	利用できる機能	登録先
DISGENET_API_KEY	遺伝子と疾患の関連	https://disgenet.com/academic-apply
OMIM_API_KEY	メンデル遺伝／希少疾患	https://omim.org/api
ONCOKB_API_TOKEN	精密腫瘍学	https://www.oncokb.org/apiAccess
UMLS_API_KEY	医療用語	https://uts.nlm.nih.gov/uts/

全ティアのキー一覧については、API_KEYS_REFERENCE.md をご覧ください。

キーの追加：

チャットモード — MCP 設定の env ブロックに追加します：

"env": {
  "PYTHONIOENCODING": "utf-8",
  "NCBI_API_KEY": "your_key_here"
}

CLI — 環境変数を設定します：

export NCBI_API_KEY="your_key_here"       # Current session
echo 'export NCBI_API_KEY="key"' >> ~/.zshrc  # Persist across sessions

SDK — CLI と同様に設定します（export または .env ファイル）。

ステップ 4：一緒にテストする

説明するだけでなく、ユーザーと一緒に実行してください。

チャットモード：アプリを再起動するようユーザーに依頼します。その後、自分でテスト呼び出しを実行します：

1. 「PubMed」を指定して list_tools または grep_tools を実行し、ツールが表示されることを確認します
2. execute_tool("PubMed_search_articles", {"query": "CRISPR", "max_results": 1}) を実行し、動作することを確認します
3. 「動作しました！2,700 個以上の科学ツールを利用できます」と伝えて、一緒に喜びましょう。

CLI：一緒に実行します：

tu status && tu find 'protein' && tu run PubMed_search_articles '{"query": "CRISPR", "max_results": 1}'

SDK：SDK セットアップの Python スニペットを一緒に実行します。

問題がある場合：最もよくある原因は、アプリが再起動されていないこと、uv が PATH にないこと（ターミナルを開き直します）、設定の JSON 構文エラーです。

ステップ 5：スキルをインストールする（チャットモードに推奨）

スキルはあらかじめ構築された研究ワークフローで、基本的なツール呼び出しを専門的な調査に変えます。

チャットモードのユーザー：エージェントがユーザーに代わってこれを実行します：

git clone --depth 1 https://github.com/mims-harvard/ToolUniverse.git /tmp/tu-skills

次に、クライアントのスキルディレクトリにコピーします：

クライアント	コマンド
Cursor	mkdir -p .cursor/skills && cp -r /tmp/tu-skills/skills/* .cursor/skills/
Claude Code	mkdir -p .claude/skills && cp -r /tmp/tu-skills/skills/* .claude/skills/
Windsurf	mkdir -p .windsurf/skills && cp -r /tmp/tu-skills/skills/* .windsurf/skills/
Codex	mkdir -p .agents/skills && cp -r /tmp/tu-skills/skills/* .agents/skills/
Gemini CLI	mkdir -p .gemini/skills && cp -r /tmp/tu-skills/skills/* .gemini/skills/

クリーンアップ：rm -rf /tmp/tu-skills

スキルはユーザーの質問に応じて自動的に有効になります。「医薬品メトホルミンについて調査して」や「がんにおける CRISPR について、文献ではどのように述べられていますか？」と試してみてください。

CLI のユーザー：スキルは AI チャットエージェント向けに設計されています。代わりに tu find、tu info、tu run を使用してください。複数ステップのワークフロー全体を実行するには、チャットモードを使うか、SDK パイプラインを構築してください。

次は？（初回利用をガイド）

候補を並べるだけでなく、ユーザーと一緒に実際のデモを実行してください。

研究関心に基づいてデモ用のクエリを選択します（ステップ 3）：

関心分野	最初のクエリ	スキル
文献	"What does the literature say about CRISPR in cancer?"	literature-deep-research
創薬	"Research the drug metformin"	drug-research
タンパク質構造	"Find protein structures for human EGFR"	protein-structure-retrieval
ゲノミクス	"What genes are associated with type 2 diabetes?"	disease-research
希少疾患	"Patient with progressive ataxia and oculomotor apraxia — differential diagnosis?"	rare-disease-diagnosis
医薬品の安全性	"What are the adverse events for pembrolizumab?"	pharmacovigilance
一般	"Research the drug aspirin"	drug-research

デモを実行します — スキルを呼び出し、実際の結果を表示します。

プロンプト早見表（デモ後に共有）

チャットモードのユーザー：

1. "Research the drug [name]" — 医薬品の詳細なプロファイル
2. "Research [disease]" — 包括的な疾患分析
3. "What are the known targets of [drug]?" — 標的に関する情報
4. "What does the literature say about [topic]?" — 詳細な文献レビュー
5. "Find protein structures for [protein]" — 3D 構造
6. "Is [variant] pathogenic?" — バリアントの解釈
7. "What drugs could be repurposed for [disease]?" — ドラッグリポジショニング
8. "What are the adverse events for [drug]?" — 安全性分析
9. "Find clinical trials for [disease/drug]" — 臨床試験のマッチング
10. "What are the protein interactions for [gene]?" — 相互作用ネットワーク
11. "What are the clinical guidelines for [condition]?" — 診療ガイドライン
12. "Check drug interactions between [drug1] and [drug2]" — 医薬品相互作用の分析

自然な言葉で尋ねるだけで大丈夫です。検索するデータベースは私が判断します。

CLI ユーザー：

tu find 'drug safety'           # ツールを検索
tu info PubMed_search_articles  # パラメーターを確認
tu run PubMed_search_articles '{"query": "CRISPR cancer", "max_results": 3}'
tu run UniProt_get_entry_by_accession '{"accession": "P12345"}'
tu run FAERS_count_death_related_by_drug '{"medicinalproduct": "metformin"}'

エージェントのメモリに記述

セットアップ後、エージェントのメモリファイルにリマインダーを記述し、今後のセッションで ToolUniverse が利用可能であることを確認できるようにします。

クライアント	ファイル
Cursor	.cursor/rules/tooluniverse.md
Claude Code	CLAUDE.md または .claude/CLAUDE.md（追記）
Windsurf	.windsurf/rules/tooluniverse.md
VS Code/Copilot	.github/copilot-instructions.md（追記）
Codex / OpenCode	AGENTS.md（追記）
Gemini CLI	GEMINI.md（追記）
Cline	.clinerules/tooluniverse.md
Trae	.trae/rules/tooluniverse.md

内容：

# ToolUniverse
For any scientific research question (drugs, genes, proteins, diseases, literature, clinical trials, etc.), invoke the `tooluniverse` skill — it routes to specialized research skills and 2,700+ database tools.

上書きせずに追記します。まず既存のセクションを確認してください。ユーザーの許可を求めてください。

チーム／プロジェクトレベルのセットアップ

チームまたは共有プロジェクト向けに ToolUniverse をセットアップする場合：

共有 API キー：プロジェクトのルートに .env ファイルを作成し、すべてのキーを記述します。ほとんどのクライアントと CLI／SDK は、.env からキーを自動的に読み込みます：

NCBI_API_KEY=your_shared_key
NVIDIA_API_KEY=your_shared_key

プロジェクトレベルの MCP 設定（チームメンバー全員が ToolUniverse を自動的に利用できるようにするため）：

• Cursor：プロジェクトのルートに .cursor/mcp.json
• Claude Code：プロジェクトのルートに .mcp.json
• VS Code：プロジェクトのルートに .vscode/mcp.json
• Windsurf：Windsurf UI からプロジェクトレベルで設定

プロジェクトレベルのスキル：プロジェクトにスキルをインストールし（例：.cursor/skills/）、チームメンバー全員で共有できるようにします。

チーム全体のアップグレード：各チームメンバーが uv cache clean tooluniverse を実行し、アプリを再起動します。特定のバージョンに固定するには、MCP 設定で "args": ["tooluniverse==X.Y.Z"] を使用します。

よくある問題

問題	解決方法
error: externally-managed-environment (PEP 668)	システムの pip はインストールを拒否します。uv を使用してください — uv venv --python 3.12 && source .venv/bin/activate && uv pip install tooluniverse。sudo pip や --break-system-packages は使用しないでください。
python3 -m venv が ensurepip で失敗する	Homebrew Python (3.13/3.14) には、正常に動作する ensurepip がありません。uv venv --python 3.12 を使用してください — uv は独自の Python を提供します。
uv pip install → "No virtual environment found"	先に uv venv を実行するか、tu コマンドだけを使用する場合は uv tool install tooluniverse を実行してください。
requires-python >= 3.10	uv python install 3.12
uvx: command not found	手順 2 のインストールスクリプトを実行し、ターミナルを再起動してください
コンテキストウィンドウのオーバーフロー	uvx tooluniverse で確認してください（コンパクトモードがデフォルトです）
ツールの実行時に ModuleNotFoundError が発生する	オプションの追加パッケージが不足しています。tooluniverse-doctor を実行して不足しているグループを確認し、uv pip install 'tooluniverse[ml]'（または [visualization]、[bioinformatics]、[all]）を実行してください。
ツールは一覧に表示されるが、実行すると失敗する	追加パッケージに依存するツールでは正常な状態です — tu status が数えるのは読み込まれた設定であり、インストール済みの依存関係ではありません。tooluniverse-doctor で不足しているグループを確認できます。
MCP サーバーが起動しない	テストするには、ターミナルで uvx tooluniverse を実行してください。python3 -m json.tool < <config> で設定を検証してください。
API キーの 401/403 エラー	env ブロックのキーを確認し、アプリを再起動して、キー名を確認してください
アップグレードが必要	uv cache clean tooluniverse を実行してからアプリを再起動してください

ヘルスチェック：tooluniverse-doctor は、読み込みに失敗したツールと、インストールされていないオプションの依存関係グループを報告します。ツールで予期しないエラーが発生した場合は、まずこれを使用してください。

[all] にすべてが含まれるわけではありません：dev, docs, graph, visualization, space, embedding, ml, bioinformatics が対象です。singlecell、smolagents、client、 build は名前を指定してインストールする必要があります。

まだ解決しませんか？ GitHub のイシューまたは Shanghua Gao にメールでお問い合わせください。

クイックリファレンス

• デフォルト：uvx tooluniverse — 自動インストール、コンパクトモード
• アップグレード：uv cache clean tooluniverse ＋ 再起動
• すべての科学系 API キーは無料です
• スキル：https://github.com/mims-harvard/ToolUniverse/tree/main/skills