---
id: mims-harvard/ToolUniverse/setup-tooluniverse
version: "46581546"
license: Apache-2.0
install: manual
updated: 2026-07-27
---

# setup-tooluniverse — ToolUniverse setup guides you through installing and configuring the platform across three access modes: chat-based MCP for AI assistants, command-line interface with nine subcommands, or Python SDK for automation. The skill covers uv installation, MCP configuration for 12+ AI clients, full CLI reference, Coding API patterns, API key setup, and troubleshooting.

Publisher: mims-harvard · Stars: 1595 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/mims-harvard/ToolUniverse`

## SKILL.md

# 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](https://claude.ai/download).

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

```bash
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:

```bash
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.

```bash
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):
```python
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):
```python
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):
```python
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.**

```bash
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):
```json
{
  "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:
> ```bash
> 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](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):**

| Key | Unlocks | Free? | Registration |
|-----|---------|-------|-------------|
| `NCBI_API_KEY` | PubMed (rate limit 3→10/s) | Yes | https://account.ncbi.nlm.nih.gov/settings/ |
| `NVIDIA_API_KEY` | 16 tools: AlphaFold2, docking, genomics | Yes | https://build.nvidia.com |
| `BIOGRID_API_KEY` | Protein interaction queries | Yes | https://webservice.thebiogrid.org/ |
| `FDA_API_KEY` | FDA adverse events, drug labels (rate 240→1000/min) | Yes | https://open.fda.gov/apis/authentication/ |

**Tier 2 (Specialized — based on interests):**

| Key | Unlocks | Registration |
|-----|---------|-------------|
| `DISGENET_API_KEY` | Gene-disease associations | https://disgenet.com/academic-apply |
| `OMIM_API_KEY` | Mendelian/rare disease | https://omim.org/api |
| `ONCOKB_API_TOKEN` | Precision oncology | https://www.oncokb.org/apiAccess |
| `UMLS_API_KEY` | Medical terminology | https://uts.nlm.nih.gov/uts/ |

See [API_KEYS_REFERENCE.md](API_KEYS_REFERENCE.md) for the complete list with all tiers.

**Adding keys:**

Chat mode — add to `env` block in MCP config:
```json
"env": {
  "PYTHONIOENCODING": "utf-8",
  "NCBI_API_KEY": "your_key_here"
}
```

CLI — set environment variables:
```bash
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 1200+ scientific tools."

**CLI**: Run together:
```bash
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:
```bash
git clone --depth 1 https://github.com/mims-harvard/ToolUniverse.git /tmp/tu-skills
```

Then copy to client's skill directory:

| Client | Command |
|--------|---------|
| 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/` |

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

| Interest | First query | Skill |
|----------|------------|-------|
| Literature | "What does the literature say about CRISPR in cancer?" | literature-deep-research |
| Drug discovery | "Research the drug metformin" | drug-research |
| Protein structure | "Find protein structures for human EGFR" | protein-structure-retrieval |
| Genomics | "What genes are associated with type 2 diabetes?" | disease-research |
| Rare diseases | "Patient with progressive ataxia and oculomotor apraxia — differential diagnosis?" | rare-disease-diagnosis |
| Drug safety | "What are the adverse events for pembrolizumab?" | pharmacovigilance |
| General | "Research the drug aspirin" | drug-research |

**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:**
> ```bash
> 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.

| Client | File |
|--------|------|
| Cursor | `.cursor/rules/tooluniverse.md` |
| Claude Code | `CLAUDE.md` or `.claude/CLAUDE.md` (append) |
| Windsurf | `.windsurf/rules/tooluniverse.md` |
| VS Code/Copilot | `.github/copilot-instructions.md` (append) |
| Codex / OpenCode | `AGENTS.md` (append) |
| Gemini CLI | `GEMINI.md` (append) |
| Cline | `.clinerules/tooluniverse.md` |
| Trae | `.trae/rules/tooluniverse.md` |

**Content:**
```markdown
# 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 1,200+ 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

| Issue | Fix |
|-------|-----|
| `error: externally-managed-environment` (PEP 668) | System `pip` refuses to install. Use `uv` — `uv venv --python 3.12 && source .venv/bin/activate && uv pip install tooluniverse`. Never `sudo pip` or `--break-system-packages`. |
| `python3 -m venv` fails at `ensurepip` | Homebrew Python (3.13/3.14) is missing a working `ensurepip`. Use `uv venv --python 3.12` — `uv` supplies its own Python. |
| `uv pip install` → "No virtual environment found" | Run `uv venv` first, or use `uv tool install tooluniverse` for just the `tu` command. |
| `requires-python >= 3.10` | `uv python install 3.12` |
| `uvx: command not found` | Run install script from Step 2, restart terminal |
| Context window overflow | Verify using `uvx tooluniverse` (compact mode is default) |
| `ModuleNotFoundError` at tool runtime | An optional extra is missing. Run `tooluniverse-doctor` to see which group, then `uv pip install 'tooluniverse[ml]'` (or `[visualization]`, `[bioinformatics]`, `[all]`). |
| Tools listed but fail when run | Normal for extras-backed tools — `tu status` counts loaded configs, not installed dependencies. `tooluniverse-doctor` reports which groups are missing. |
| MCP server won't start | Test: `uvx tooluniverse` in terminal. Validate config with `python3 -m json.tool < <config>`. |
| API key 401/403 | Check key in `env` block, restart app, verify key name |
| Upgrade needed | `uv cache clean tooluniverse` then restart app |

**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](https://github.com/mims-harvard/ToolUniverse/issues) or email [Shanghua Gao](mailto:shanghuagao@gmail.com).

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


[View on SkillFed](https://skillfed.io/mims-harvard/ToolUniverse/setup-tooluniverse) · [View on GitHub](https://github.com/mims-harvard/ToolUniverse)