tooluniverse-claude-code-plugin

# Install the ToolUniverse Plugin for Claude Code

One-step install of the ToolUniverse plugin: MCP server with 1000+ tools, 120+ research skills, slash commands, and the research agent — all auto-configured.

## Prerequisites (check once)

```bash
uv --version      # must exist; if not:  curl -LsSf https://astral.sh/uv/install.sh | sh
claude --version  # Claude Code CLI; if not: https://claude.com/claude-code
```

## Install (two commands)

```bash
# 1. Register the ToolUniverse marketplace from GitHub
claude plugin marketplace add mims-harvard/ToolUniverse

# 2. Install the plugin
claude plugin install tooluniverse@tooluniverse
```

That's it. Restart Claude Code. The MCP server auto-starts via `uvx tooluniverse` on first use (~30 s cold start, instant after).

### Important: Remove global skills if previously installed

If you previously installed ToolUniverse skills globally (via `tooluniverse-install-skills` or manual copy), **remove them**. The plugin includes all skills — global copies interfere with the plugin's skill routing.

```bash
# Check for global skills
ls ~/.claude/skills/tooluniverse-* 2>/dev/null | wc -l

# Remove them (the plugin replaces them)
rm -rf ~/.claude/skills/tooluniverse-*
rm -rf ~/.claude/skills/create-tooluniverse-skill
rm -rf ~/.claude/skills/setup-tooluniverse
```

### Pin the tool version (optional, for reproducibility)

The MCP server runs the `tooluniverse` PyPI package via `uvx`. To lock tool behavior for a long-running analysis, pin the package version in the plugin's `.mcp.json` — change the args to:

```json
"args": ["tooluniverse@1.2.2"]
```

Replace `1.2.2` with any released version from https://pypi.org/project/tooluniverse/. Restart Claude Code to apply. (`.mcp.json` location is shown under "API keys" below.)

## Verify it worked

```bash
claude plugin list
# Expect: tooluniverse  (enabled)
```

Inside Claude Code, just ask naturally:
```
What are the top mutated genes in breast cancer?
Research the drug metformin.
```

The router skill auto-dispatches to the right specialized skill — no command prefix needed.

## What you get

| Component | What it does | How to invoke |
|---|---|---|
| **MCP server** | 1000+ tools via `find_tools`, `get_tool_info`, `execute_tool` | Auto-loaded; no action needed |
| **`/tooluniverse:research`** | Multi-database investigation inline in this chat (you see each step) | Slash command |
| **`/tooluniverse:translate-id`** | Resolve an ID across all relevant namespaces | Slash command |
| **`/tooluniverse:cross-validate`** | Verify a claim across 3+ independent databases | Slash command |
| **`/tooluniverse:compare`** | N-way side-by-side comparison with domain-appropriate columns | Slash command |
| **`/tooluniverse:literature-sweep`** | Graded mini-review across PubMed + EuropePMC + Semantic Scholar | Slash command |
| **`/tooluniverse:researcher`** | Same investigation as `research`, delegated to a forked subagent | Slash command |
| **120+ skills** | Structured workflows (drug research, variant interpretation, pharmacovigilance, CRISPR screens, statistical modeling, etc.) | Auto-activate on matching questions |

## API keys (optional, but recommended)

Most tools work without keys. For enhanced access, add the keys you care about to the MCP server's `env` block. Locate the installed plugin's `.mcp.json`:

```bash
# Show component inventory + on-disk location:
claude plugin details tooluniverse

# Or find the file directly:
find ~/.claude/plugins -name '.mcp.json' -path '*tooluniverse*'

# Typical install location after marketplace install:
# ~/.claude/plugins/cache/tooluniverse/tooluniverse/<version>/.mcp.json
```

```json
{
  "mcpServers": {
    "tooluniverse": {
      "command": "uvx",
      "args": ["tooluniverse"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "NCBI_API_KEY": "your_key",
        "NVIDIA_API_KEY": "your_key",
        "ONCOKB_API_TOKEN": "your_token"
      }
    }
  }
}
```

Full API-key list: `setup-tooluniverse` skill → `API_KEYS_REFERENCE.md`.

## Update

```bash
claude plugin update tooluniverse
# Also refresh the MCP server's tool cache:
uv cache clean tooluniverse
```

Restart Claude Code.

## Uninstall

```bash
claude plugin uninstall tooluniverse
claude plugin marketplace remove tooluniverse
```

## Alternative install paths

### Clone + local install (air-gapped or forks)

```bash
git clone https://github.com/mims-harvard/ToolUniverse.git
cd ToolUniverse
claude plugin marketplace add ./
claude plugin install tooluniverse@tooluniverse
```

### Download the release zip (no git needed)

Grab `tooluniverse-plugin-vX.Y.Z.zip` from https://github.com/mims-harvard/ToolUniverse/releases, unzip, then:

```bash
claude plugin marketplace add /path/to/unzipped-dir
claude plugin install tooluniverse@tooluniverse
```

## Troubleshooting

| Symptom | Fix |
|---|---|
| `marketplace add` fails with "no marketplace.json" | Ensure you're using `mims-harvard/ToolUniverse` (owner/repo), not the plugin subdir. |
| `uvx: command not found` | Install `uv` (see Prerequisites), reopen terminal. |
| MCP server won't start | Test in terminal: `uvx tooluniverse`. If it fails there, it's an `uv`/Python issue. |
| Plugin installs but tools missing | Restart Claude Code. First launch downloads the package (~30 s). |
| `requires-python >= 3.10` | `uv python install 3.12` |
| Tools feel outdated | `uv cache clean tooluniverse` then restart Claude Code. |
| New release not picked up / tools run an OLD version | Run `uv tool list \| grep tooluniverse`. If it's listed, a global `uv tool install` is **shadowing** the plugin's `uvx` (uvx prefers an installed tool over the latest published version). Fix: `uv tool uninstall tooluniverse`, then restart. Normal users without that install always get the latest automatically. |

Still stuck: https://github.com/mims-harvard/ToolUniverse/issues

## Automated diagnosis & repair

If the table above didn't fix it, hand this skill to an agent — *"read the
tooluniverse-c