setup-tooluniverse

Setup ToolUniverse

Guide the user step-by-step through setting up ToolUniverse.

Agent Behavior

• Detect language from user's first message. Respond in their language; keep commands/URLs in English.
• Go one step at a time. Ask before proceeding.
• Use AskQuestion for structured choices.
• Explain briefly in plain language. Celebrate small wins.
• When something goes wrong, help troubleshoot before moving on.

Internal Notes (do not show)

ToolUniverse has 2,700+ tools. The tooluniverse command enables compact mode automatically, exposing only 5 core MCP tools (list_tools, grep_tools, get_tool_info, execute_tool, find_tools) while keeping all tools accessible via execute_tool.

What is ToolUniverse?

Always explain first, in plain language:

ToolUniverse is free, open-source software connecting to 2,000+ scientific databases (PubMed, UniProt, ChEMBL, FAERS, ClinicalTrials.gov, etc.). Instead of visiting each website, you search from one place. Think of it like a universal remote for scientific databases.

Why AI assistants? The AI reads your question, figures out which databases to search, runs queries, and summarizes results. You just ask your question.

Step 1: Choose How to Use It

Present using AskQuestion:

Options: "I want to ask questions" → Chat mode | "Quick try" → CLI | "I write Python" → SDK | "I don't know" → Recommend Chat mode

If Chat mode, ask which app (AskQuestion): Cursor, Claude Desktop, VS Code/Copilot, Windsurf, Claude Code, Gemini CLI, Codex, Cline/Trae/Antigravity/OpenCode. "I don't have any" → Recommend Claude Desktop.

Step 2: Install uv

Only prerequisite: uv (manages everything else automatically).

Terminal help (if needed): Mac: Cmd+Space → "Terminal" → Enter. Windows: Win key → "PowerShell" → Enter.

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

(This is a safe, standard command that downloads and installs uv, a small package manager. It's widely used by Python developers. Close and reopen your terminal after it finishes.)

Verify: uv --version

CLI Setup

Make sure Step 2 is done, then try:

uvx --from tooluniverse tu status              # How many tools?
uvx

First run takes ~30s (downloads package), then instant. Shortcut: uv tool install tooluniverse → then just use tu directly.

All CLI subcommands

Output flags (most commands except build/serve): --json (pretty) or --raw (compact, pipe-friendly).

Continue to Step 3 (API Keys).

SDK Setup

Install uv first (Step 2). Do not use system pip. On a current Mac (Homebrew Python 3.13/3.14) pip install tooluniverse stops with error: externally-managed-environment (PEP 668), and python3 -m venv can fail at ensurepip. uv avoids both because it downloads and manages its own Python.

uv pip install needs an active virtualenv — run uv venv first, or use uv tool install tooluniverse if you only want the tu command.

For detailed patterns, invoke the tooluniverse-sdk skill.

Optional extras: the base install covers API/database tools. Local ML, cheminformatics, and plotting tools need extras — uv pip install 'tooluniverse[ml]', [visualization], [bioinformatics], or [all]. Run tooluniverse-doctor to see which groups you are missing. Note [all] does not include singlecell, smolagents, client, or build; install those separately.

Coding API — 3 calling patterns

Pattern 1: Direct import (typed, with autocomplete):

Pattern 2: Attribute access (no import needed per tool):

Pattern 3: JSON-based (dynamic, for pipelines):

Generate typed wrappers: tu build (creates importable Python modules with autocomplete).

Agentic Tools & Code Executor

ToolUniverse also includes 23 AI-powered agentic tools (ScientificTextSummarizer, HypothesisGenerator, ExperimentalDesignScorer, peer-review tools, etc.) and 2 code executor tools (python_code_executor, python_script_runner). These are called like any other tool — via tu.run() or execute_tool(). Agentic tools require an LLM API key (e.g., OPENAI_API_KEY).

Continue to Step 3 (API Keys).

MCP Setup (Chat Mode)

Offer the two low-effort paths first. Editing JSON by hand is the fallback, not the recommendation — a mistyped comma is the single most common setup failure. Only walk through the manual path if neither option below fits.

Path A — let an AI agent do it. If the user already has any agent (Claude, Cursor, Copilot, Gemini, Codex...), they can paste this into it:

The agent handles config, keys, skills, and validation. No terminal, no JSON.

Path B — Claude Code or Codex users: one-liner, no config file at all.

Claude Code:

See the tooluniverse-claude-code-plugin skill's "Recommended: turn on auto-update" step so future releases apply without manual claude plugin update.

Codex:

See the tooluniverse-codex-plugin skill for verification, updates, and troubleshooting.

Both install the MCP server plus 180+ skills in one step. Google Antigravity users: see the tooluniverse-antigravity-plugin skill instead — its install flow differs (agy plugin install, not a marketplace add).

Manual config (fallback)

Make sure Step 2 is done (uv --version works).

Config file help (if user seems unfamiliar): Config files are plain text that store settings — like a preference list for the app. You don't need to understand the format; just paste exactly what's shown below. Most apps have a Settings button that opens the file for you (see table). If the file is empty, paste the entire block. If it already has content, the agent should help merge it.

Default config (same for most clients):

Paste safely. Copy the block whole — do not retype it. If the file already has an mcpServers block, add only the "tooluniverse": { ... } entry inside it and put a comma after the previous entry. If the file was empty, paste the whole block. Then validate before restarting the app:

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

A trailing comma after the last entry, or a missing one between entries, is the usual cause of "MCP server won't start".

args — ["tooluniverse"] vs ["--refresh", "tooluniverse"]: plain is the default and starts fast from uv's cache, but can stay on a cached older release until you run uv cache clean tooluniverse. Adding --refresh checks PyPI for the newest version on every launch — always current, a few seconds slower to start. Use plain unless the user specifically wants auto-updates.

Config file locations:

Different formats: VS Code uses "servers" key with "type": "stdio". Codex uses TOML. OpenCode uses "mcp" key. See references/mcp-configs.md for these.

Continue to Step 3 (API Keys).

Step 3: API Keys

Many tools work without keys, but some unlock powerful features. Ask research interests first (AskQuestion):

• Literature / Drug discovery / Protein structure / Genomics / Rare diseases / Enzymology / Patent search / AI analysis / All / Skip

Map to recommended keys (2-4 to start). Walk through one at a time: explain what it unlocks, give registration link, wait for key, add to config.

Tier 1 (Core — recommend for most users):

Tier 2 (Specialized — based on interests):

See API_KEYS_REFERENCE.md for the complete list with all tiers.

Adding keys:

Chat mode — add to env block in MCP config:

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

CLI — set environment variables:

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

SDK — same as CLI (export or .env file).

Step 4: Test Together

Don't just tell — do it WITH the user.

Chat mode: Ask user to restart app. Then run a test call yourself:

1. list_tools or grep_tools with "PubMed" — confirm tools visible
2. execute_tool("PubMed_search_articles", {"query": "CRISPR", "max_results": 1}) — confirm it works
3. Celebrate: "It works! You have access to 2,700+ scientific tools."

CLI: Run together:

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

SDK: Run the Python snippet from SDK Setup together.

If issues: Most common: app not restarted, uv not in PATH (reopen terminal), JSON syntax error in config.

Step 5: Install Skills (Recommended for Chat Mode)

Skills are pre-built research workflows that turn basic tool calls into expert investigations.

Chat mode users: The agent should run this for the user:

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

Then copy to client's skill directory:

Clean up: rm -rf /tmp/tu-skills

Skills activate automatically based on user's question. Try: "Research the drug metformin" or "What does the literature say about CRISPR in cancer?"

CLI users: Skills are designed for AI chat agents. Use tu find, tu info, tu run instead. For full multi-step workflows, use Chat mode or build SDK pipelines.

What's Next? (Guided First Use)

Don't list suggestions — run a live demo WITH the user.

Pick a demo query based on research interests (from Step 3):

Run the demo — invoke the skill and show real results.

Prompt cheat sheet (share after demo)

Chat mode users:

1. "Research the drug [name]" — full drug profile
2. "Research [disease]" — comprehensive disease analysis
3. "What are the known targets of [drug]?" — target intelligence
4. "What does the literature say about [topic]?" — deep literature review
5. "Find protein structures for [protein]" — 3D structures
6. "Is [variant] pathogenic?" — variant interpretation
7. "What drugs could be repurposed for [disease]?" — repurposing
8. "What are the adverse events for [drug]?" — safety analysis
9. "Find clinical trials for [disease/drug]" — trial matching
10. "What are the protein interactions for [gene]?" — interaction network
11. "What are the clinical guidelines for [condition]?" — practice guidelines
12. "Check drug interactions between [drug1] and [drug2]" — DDI analysis

Just ask naturally — I'll figure out which databases to search.

CLI users:

tu find 'drug safety'           # Discover tools
tu info PubMed_search_articles  # Check parameters
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"}'

Write Agent Memory

After setup, write a reminder to the agent's memory file so future sessions know ToolUniverse is available.

Content:

# 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.

Append (don't overwrite). Check for existing section first. Ask user permission.

Team / Project-Level Setup

If setting up ToolUniverse for a team or shared project:

Shared API keys: Create a .env file at the project root with all keys. Most clients and the CLI/SDK will pick up keys from .env automatically:

NCBI_API_KEY=your_shared_key
NVIDIA_API_KEY=your_shared_key

Project-level MCP config (so all team members get ToolUniverse automatically):

• Cursor: .cursor/mcp.json in project root
• Claude Code: .mcp.json in project root
• VS Code: .vscode/mcp.json in project root
• Windsurf: project-level via Windsurf UI

Project-level skills: Install skills into the project (e.g., .cursor/skills/) so all team members share them.

Team-wide upgrade: Each team member runs uv cache clean tooluniverse and restarts their app. To pin a specific version, use "args": ["tooluniverse==X.Y.Z"] in the MCP config.

Common Issues

Health check: tooluniverse-doctor reports tools that failed to load and which optional dependency groups are not installed. Use it first whenever a tool errors unexpectedly.

[all] is not everything: it covers dev, docs, graph, visualization, space, embedding, ml, bioinformatics. singlecell, smolagents, client, and build must be installed by name.

Still stuck? GitHub issues or email Shanghua Gao.

Quick Reference

• Default: uvx tooluniverse — auto-installs, compact mode
• Upgrade: uv cache clean tooluniverse + restart
• All scientific API keys are free
• Skills: https://github.com/mims-harvard/ToolUniverse/tree/main/skills