mims-harvard/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)

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": ["[email protected]"]

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

| 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:verify-references | Check that cited references are real and accurately described, including retraction status | Slash command | | /tooluniverse:self-review | Generate weighted success criteria for a task and check work against them (what's missing / done well) | Slash command | | /tooluniverse:setup-keys | Configure ToolUniverse API keys | 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:

# 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

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