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)

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

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

Recommended: turn on auto-update

Third-party marketplaces default to no auto-update — without this, new tools/skills only reach you when you remember to run claude plugin update tooluniverse (see Update below). Turn it on once:

python3 -c "
import json, pathlib, sys
p = pathlib.Path.home() / '.claude/plugins/known_marketplaces.json'
d = json.loads(p.read_text())
if 'tooluniverse' not in d:
    sys.exit('Run the marketplace add command above first')
d['tooluniverse']['autoUpdate'] = True
p.write_text(json.dumps(d, indent=2))
print('autoUpdate enabled for tooluniverse')
"

Equivalent interactive path: /plugin → Marketplaces → tooluniverse → Enable auto-update.

With this on, Claude Code checks for marketplace + plugin updates in the background after each session start (up to a ~10 min random delay) and updates the installed plugin on disk automatically. You'll get a /reload-plugins prompt when an update lands, or it applies on your next launch — no more manual claude plugin update.

This is local, per-machine state — it can't be shipped as a default from the plugin's own manifest. marketplace.json has no autoUpdate field; Claude Code intentionally keeps this a per-installation trust boundary so a publisher can't force silent auto-updates onto a user's machine.

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.

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

"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

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

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:

# 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

{
  "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

If you enabled auto-update above, this happens automatically in the background — no action needed.

Otherwise, update manually:

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

Restart Claude Code.

Uninstall

claude plugin uninstall tooluniverse
claude plugin marketplace remove tooluniverse

Alternative install paths

Clone + local install (air-gapped or forks)

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:

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

Troubleshooting

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-claude-code-plugin skill and diagnose & fix my plugin install" — or run these checks yourself in order. Each is safe and idempotent; apply the FIX for whatever fails, then restart Claude Code.

# 1. Is uv/uvx installed?  (most common cause of "no tools at all")
command -v uvx || echo "FIX: curl -LsSf https://astral.sh/uv/install.sh | sh"

# 2. Can the MCP package actually resolve + run?  (non-hanging proxy for the server)
uvx --from tooluniverse tu --version || echo "FIX: uv/Python issue — see steps 1 and 5"

# 3. Running an OLD version even after updating?  (non-obvious!)
uv tool list | grep -q tooluniverse \
  && echo "FIX: uv tool uninstall tooluniverse   (a global install shadows the plugin's uvx)" \
  || echo "ok: nothing shadowing uvx"

# 4. A new pip version was released but tools still stale?  force a refresh
uv cache clean tooluniverse        # or one-shot: uvx --refresh tooluniverse --version

# 5. Python too old (requires >= 3.10)?
uv python install 3.12

# 6. Global skills interfering with the plugin's routing?
ls ~/.claude/skills/tooluniverse-* 2>/dev/null && echo "FIX: rm -rf ~/.claude/skills/tooluniverse-*"

# 7. Is the plugin actually enabled?
claude plugin list | grep tooluniverse || echo "FIX: claude plugin install tooluniverse@tooluniverse"

An agent can run the whole sequence, apply each FIX, and tell you to restart — you don't need to understand the internals.

For plugin maintainers

This skill documents the user-facing install flow. The plugin source lives at /plugin in the repo with its own .claude-plugin/plugin.json and .mcp.json. The root .claude-plugin/marketplace.json is what makes claude plugin marketplace add mims-harvard/ToolUniverse work directly — it lists the plugin with "source": "./plugin".

When cutting a plugin release:

• Easiest: put [release:patch] (or :minor/:major) in a commit message that touches plugin/ or .claude-plugin/ on main. auto-release.yml runs scripts/release-plugin.sh, which bumps plugin/.claude-plugin/plugin.json + root .claude-plugin/marketplace.json, commits, and tags; the tag push triggers release-plugin.yml to build the zip + GitHub Release. (Or run "Auto-release plugin" from the Actions UI.)
• The next-version baseline is max(plugin.json, latest vX.Y.Z tag), so a manifest that has drifted behind the tag line won't collide with an existing tag.
• Plugin auto-update reaches users as soon as the version-bump commit lands on main (independent of the tag/zip).

The pip package (tooluniverse on PyPI) is a SEPARATE release line: bump pyproject.toml → publish-pypi.yml publishes it (→ publish-mcp-registry.yml). Plugin and pip versions need NOT move together — uvx tooluniverse auto-resolves to the latest published pip version for users, so plugin-only and pip-only releases are both fine.