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 1200+ 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:

Mode	What it means	Who it's for
Chat mode	Ask questions to an AI assistant. No coding.	Most researchers.
Command line	Type short commands in Terminal.	Quick tests. Terminal-comfortable users.
Python code	Write scripts for automated pipelines.	Programmers.

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 --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"}'

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

All CLI subcommands

Command	What it does	Example
tu status	Show tool count and top categories	tu status
tu list	List tools (modes: names, categories, basic, by_category, summary, custom)	tu list --mode basic --limit 20
tu find	Search by natural language (keyword scoring, no API key needed)	tu find 'protein structure analysis'
tu grep	Text/regex pattern search	tu grep '^UniProt' --mode regex
tu info	Show tool parameters and schema	tu info PubMed_search_articles
tu run	Execute a tool	tu run PubMed_search_articles '{"query": "CRISPR"}'
tu test	Test a tool with its example inputs	tu test UniProt_get_entry_by_accession
tu build	Generate typed Python wrappers for Coding API (also regenerates the internal lazy-load registry in place — unaffected by --output)	tu build --output ./my_tools
tu serve	Start MCP stdio server (same as uvx tooluniverse)	tu serve

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 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 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):

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

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

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

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

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

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:

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

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

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

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

Installs MCP server + 115 skills + slash commands in one step. Then see the tooluniverse-claude-code-plugin skill's "Recommended: turn on auto-update" step so future releases apply without manual claude plugin update.

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):

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

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:

Client	File	How to Access
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 or edit directly (or use plugin — see above)
Windsurf	~/.codeium/windsurf/mcp_config.json	MCP hammer icon → Configure
Cline	cline_mcp_settings.json	Cline panel → MCP Servers → Configure
Gemini CLI	~/.gemini/settings.json	gemini mcp add or edit directly
Trae	.trae/mcp.json	Ctrl+U → AI Management → MCP → Configure

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

---

Content truncated.