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:

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 '{"drug_name": "metformin"}'

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

All CLI subcommands

Output flags (most commands except build/serve): --json (pretty) or --raw (compact, pipe-friendly).

Continue to Step 3 (API Keys).

SDK Setup

Make sure Step 2 is done. For detailed patterns, invoke the tooluniverse-sdk skill.

uv pip install tooluniverse

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)

Make sure Step 2 is done (uv --version works).

Add ToolUniverse to your app's config

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

Config file locations:

Claude Code users: skip manual MCP config — use the plugin instead. Invoke the tooluniverse-claude-code-plugin skill or run:

```bash

claude plugin marketplace add mims-harvard/ToolUniverse

claude plugin install tooluniverse@tooluniverse

```

This installs MCP server + 115 skills + slash commands in one step.

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

Tier 2 (Specialized — based on interests):

See API_KEYS_REFERENCE.md for the complete list with all tiers.

Adding keys:

Chat mode — add to env block in MCP config:

"env": {
  "PYTHONIOENCODING": "utf-8",
  "NCBI_API_KEY": "your_key_here"
}

CLI — set environment variables:

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:

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:

git clone --depth 1 https://github.com/mims-harvard/ToolUniverse.git /tmp/tu-skills

Then copy to client's skill directory:

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

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 '{"drug_name": "metformin"}'

```

Write Agent Memory

After setup, write a reminder to the agent's memory file so future sessions know ToolUniverse is available.

Content:

# 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

Still stuck? GitHub issues or email Shanghua Gao.

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

ToolUniverse API Keys Reference

Detailed guide for every API key used by ToolUniverse. Use this when walking users through key setup.

---

Tier 1: Core Scientific Keys

NCBI_API_KEY

• Service: NCBI (National Center for Biotechnology Information) / PubMed
• Required: No (optional, but strongly recommended)
• Tools that use it: PubMed_search_articles, PubMed_get_article, and 3 more PubMed tools
• What it does: Increases PubMed API rate limit from 3 requests/second to 10 requests/second. Without it, heavy literature searches may be throttled.
• How to get it:

1. Go to https://account.ncbi.nlm.nih.gov/ and sign in (via Google, ORCiD, eRA Commons, or Login.gov) 2. Go to Settings at https://account.ncbi.nlm.nih.gov/settings/ 3. Scroll to "API Key Management" at the bottom 4. Click "Create an API Key" 5. Copy the generated key

• Env variable: NCBI_API_KEY

NVIDIA_API_KEY

• Service: NVIDIA NIM (NVIDIA Inference Microservices)
• Required: Yes (for NIM tools)
• Tools that use it: 16 NvidiaNIM_* tools including AlphaFold2 structure prediction, molecular docking (DiffDock), ESM protein embeddings, and genomics tools
• What it does: Provides access to GPU-accelerated bioinformatics models hosted by NVIDIA. Covers protein structure prediction, molecular docking, and sequence analysis.
• How to get it:

1. Go to https://build.nvidia.com 2. Sign in or create a free NVIDIA account 3. Navigate to any NIM API (e.g., AlphaFold2) 4. Click "Get API Key" in the top right 5. Copy the key (starts with nvapi-)

• Env variable: NVIDIA_API_KEY
• Free tier: Yes, generous free credits for API calls

BIOGRID_API_KEY

• Service: BioGRID (Biological General Repository for Interaction Datasets)
• Required: Yes (tools will not work without it)
• Tools that use it: BioGRID_get_interactions
• What it does: Enables querying the BioGRID database for protein-protein interactions, genetic interactions, and chemical associations.
• How to get it:

1. Go to https://webservice.thebiogrid.org/ 2. Click "Register" to create a free account 3. After registration, your API access key will be provided 4. You can also find it under your account settings

• Env variable: BIOGRID_API_KEY

DISGENET_API_KEY

• Service: DisGeNET (Disease-Gene Network)
• Required: Yes (tools will not work without it)
• Tools that use it: 5 DisGeNET tools for gene-disease associations, variant-disease associations, and disease enrichment analysis
• What it does: Provides access to one of the largest collections of gene-disease associations, integrating data from expert-curated repositories, GWAS catalogs, and animal models.
• How to get it:

1. Go to https://disgenet.com/academic-apply (for academic/non-profit use) 2. Fill out the application with your institutional email 3. Verify your email within 24 hours 4. Wait for approval (typically within 7 days) 5. Once approved, find your API key in your account settings

• Env variable: DISGENET_API_KEY
• Note: Free for academic use; commercial use requires a license

---

Tier 2: Specialized Scientific Keys

OMIM_API_KEY

• Service: OMIM (Online Mendelian Inheritance in Man)
• Required: Yes (tools will not work without it)
• Tools that use it: 4 OMIM tools for Mendelian disease data, gene-phenotype relationships, and clinical synopses
• What it does: Provides access to the authoritative database of human genes and genetic phenotypes, particularly for inherited diseases.
• How to get it:

1. Go to https://omim.org/api 2. Click "Request API Key" 3. Fill out the registration form (academic/institutional email recommended) 4. API key is typically emailed within 1-2 business days

• Env variable: OMIM_API_KEY
• Note: Approval may take time; academic users are prioritized

ONCOKB_API_TOKEN

• Service: OncoKB (Precision Oncology Knowledge Base)
• Required: Yes (tools will not work without it)
• Tools that use it: OncoKB tools for cancer gene annotations, actionable mutations, and therapeutic implications
• What it does: Provides access to MSK's precision oncology knowledge base with FDA-recognized biomarker-drug associations, levels of evidence for therapeutic implications.
• How to get it:

1. Go to https://www.oncokb.org/apiAccess 2. Click "Request API Access" 3. Register with your institutional email 4. For academic use, select the free academic license 5. Token is provided after approval

• Env variable: ONCOKB_API_TOKEN
• Note: Free for academic/research use

UMLS_API_KEY

• Service: UMLS (Unified Medical Language System) / NLM
• Required: Yes (tools will not work without it)
• Tools that use it: 5 UMLS tools for medical concept lookup, terminology mapping, cross-referencing between medical vocabularies (ICD, SNOMED, MeSH, etc.)
• What it does: Maps between medical terminologies, finds concept definitions, and navigates hierarchical relationships between medical concepts.
• How to get it:

1. Go to https://uts.nlm.nih.gov/uts/ 2. Click "Sign Up" to create a UMLS Terminology Services account 3. You'll need to accept the UMLS license agreement 4. After approval, go to "My Profile" to find your API key

• Env variable: UMLS_API_KEY
• Note: Requires license agreement acceptance; usually instant for US-based users

USPTO_API_KEY

• Service: USPTO (United States Patent and Trademark Office)
• Required: Yes (tools will not work without it)
• Tools that use it: 6 USPTO tools for patent search, patent data retrieval, and patent analysis
• What it does: Enables searching and retrieving US patent documents, patent claims, and patent family information.
• How to get it:

1. Create a USPTO account at https://my.uspto.gov/ (if you don't have one) 2. Go to the API manager at https://account.uspto.gov/api-manager/ 3. Log in with your USPTO credentials 4. Register for an API key -- it will be emailed to you

• Env variable: USPTO_API_KEY

SEMANTIC_SCHOLAR_API_KEY

• Service: Semantic Scholar (Allen Institute for AI)
• Required: No (optional, but recommended for heavy literature use)
• Tools that use it: SemanticScholar_search_papers
• What it does: Increases rate limit from 1 request/second to 100 requests/second. Essential if doing bulk literature searches or citation analysis.
• How to get it:

1. Go to https://www.semanticscholar.org/product/api 2. Click "Request API Key" 3. Fill out the form with your use case 4. Key is typically emailed within a few days

• Env variable: SEMANTIC_SCHOLAR_API_KEY

FDA_API_KEY

• Service: openFDA
• Required: No (optional, raises rate limits)
• Tools that use it: OpenFDA tools and FAERS adverse event analytics
• What it does: Increases openFDA rate limit from 240 requests/minute to 1000 requests/minute. Useful for drug safety signal analysis.
• How to get it:

1. Go to https://open.fda.gov/apis/authentication/ 2. Enter your email to request a key 3. Key is emailed instantly

• Env variable: FDA_API_KEY

BRENDA_EMAIL + BRENDA_PASSWORD

• Service: BRENDA (Braunschweig Enzyme Database)
• Required: Yes (tools will not work without both)
• Tools that use it: 3 BRENDA tools for enzyme kinetics, substrate specificity, and enzyme functional data
• What it does: Provides access to the world's most comprehensive enzyme database with kinetic parameters (Km, Vmax, kcat), substrate/product data, and enzyme classifications.
• How to get it:

1. Go to https://brenda-enzymes.org/register.php 2. Fill in email, password, name, and scientific field 3. Complete the captcha and submit 4. Confirm your email 5. Use the email and password you registered with as the API credentials

• Env variables: BRENDA_EMAIL and BRENDA_PASSWORD
• Note: This uses your login credentials, not a separate API key

MOUSER_API_KEY

• Service: Mouser Electronics
• Required: Yes (tools will not work without it)
• Tools that use it: 4 Mouser tools for electronic component search by keyword, part number, and manufacturer
• What it does: Provides access to Mouser's comprehensive catalog of electronic components, including ICs, resistors, capacitors, microcontrollers, and more. Includes pricing, availability, datasheets, and specifications.
• How to get it:

1. Go to https://www.mouser.com/api-search/ 2. Click "Sign Up For Search API" 3. Fill out the registration form (requires business/academic email) 4. API key is typically provided instantly after email verification

• Env variable: MOUSER_API_KEY
• Free tier: Yes, 1,000 requests/day, 30 requests/minute

DIGIKEY_CLIENT_ID + DIGIKEY_CLIENT_SECRET

• Service: Digi-Key Electronics
• Required: Yes (tools will not work without both)
• Tools that use it: 4 Digi-Key tools for product search, detailed product info, category browsing, and manufacturer listings
• What it does: Provides access to Digi-Key's extensive catalog of electronic components with detailed specifications, pricing, inventory, parametric search, and technical documentation.
• How to get it:

1. Go to https://developer.digikey.com/ 2. Click "Register" to create a free developer account 3. After login, go to "Organization" → "Production Apps" 4. Click "Create Production App" 5. Fill in app details (name, description, OAuth callback URL: https://localhost/callback) 6. After creation, copy the Client ID and Client Secret

• Env variables: DIGIKEY_CLIENT_ID and DIGIKEY_CLIENT_SECRET
• Free tier: Yes, 1,000 requests/day, 120 requests/minute
• Note: Uses OAuth2 authentication with automatic token refresh. The tool handles token management automatically.

---

Tier 3: LLM Provider Keys

These keys power ToolUniverse's agentic features -- tools that use LLMs to synthesize results, plan multi-step analyses, and generate reports. At least one LLM provider key is needed for these features.

The system checks providers in this order: Azure OpenAI -> OpenRouter -> Gemini. Configure whichever you prefer.

GEMINI_API_KEY

• Service: Google Gemini
• Required: No (one of the LLM providers needed for agentic features)
• What it does: Powers agentic tools using Google's Gemini models. Good default choice due to generous free tier.
• How to get it:

1. Go to https://aistudio.google.com/apikey 2. Sign in with your Google account 3. Click "Create API Key" (a default Google Cloud project is created automatically for new users) 4. Copy the key

• Env variable: GEMINI_API_KEY
• Free tier: Yes, generous free usage limits

OPENROUTER_API_KEY

• Service: OpenRouter
• Required: No (alternative LLM provider)
• What it does: Provides access to 100+ LLM models through a single API. Pay-per-use pricing, good flexibility.
• How to get it:

1. Go to https://openrouter.ai/ 2. Sign up or log in 3. Go to https://openrouter.ai/keys 4. Click "Create Key" 5. Add credits to your account for usage

• Env variable: OPENROUTER_API_KEY

OPENAI_API_KEY

• Service: OpenAI
• Required: No (alternative LLM provider, also used for embeddings)
• What it does: Powers embedding-based tool finding and can serve as an LLM provider for agentic features.
• How to get it:

1. Go to https://platform.openai.com/ 2. Sign up or log in 3. Go to API Keys section 4. Click "Create new secret key" 5. Copy the key (starts with sk-)

• Env variable: OPENAI_API_KEY

AZURE_OPENAI_API_KEY

• Service: Azure OpenAI Service
• Required: No (enterprise alternative to direct OpenAI)
• What it does: Same capabilities as OpenAI but through Azure infrastructure. Preferred for enterprise/institutional users.
• How to get it:

1. Go to Azure Portal (https://portal.azure.com) 2. Create or navigate to your Azure OpenAI resource 3. Go to "Keys and Endpoint" in the resource 4. Copy Key 1 or Key 2

• Env variables: AZURE_OPENAI_API_KEY and optionally AZURE_OPENAI_ENDPOINT
• Note: Also set AZURE_OPENAI_ENDPOINT if not using the default endpoint

ANTHROPIC_API_KEY

• Service: Anthropic (Claude)
• Required: No (alternative LLM provider)
• What it does: Enables Claude-based features.
• How to get it:

1. Go to https://console.anthropic.com/ 2. Sign up or log in 3. Go to API Keys section 4. Create a new key

• Env variable: ANTHROPIC_API_KEY

HF_TOKEN

• Service: HuggingFace
• Required: No (optional, for model/dataset access)
• What it does: Enables access to gated HuggingFace models and datasets, and the HF Inference API for embeddings.
• How to get it:

1. Go to https://huggingface.co/settings/tokens 2. Sign up or log in 3. Click "New token" 4. Select "Read" access (sufficient for most uses) 5. Copy the token (starts with hf_)

• Env variable: HF_TOKEN
• Free tier: Yes

---

Quick Setup by Research Area

Claude Desktop Setup

⚠️ The PATH Problem — Read This Before Writing Any Config

Claude Desktop is a GUI app. It launches in a clean environment and does not inherit your shell's PATH. This means if uvx lives in ~/.local/bin/uvx (the default for the uv curl installer), Claude Desktop cannot find it — and will show a silent failure like "Failed to spawn process" or "ENOENT" with no helpful error message.

You must resolve this before writing the config. There are three ways:

---

Fix A — Homebrew (macOS, recommended, permanent)

Homebrew installs uvx to /opt/homebrew/bin/uvx (Apple Silicon) or /usr/local/bin/uvx (Intel), which Claude Desktop can always find.

brew install uv

If you already installed uv via the curl installer, also run:

brew link uv --overwrite

Verify the Homebrew binary exists (Claude Desktop will use this path directly):

/opt/homebrew/bin/uvx --version   # Apple Silicon Mac
/usr/local/bin/uvx --version      # Intel Mac

With Homebrew uv installed, the standard config works:

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

---

Fix B — Use the absolute path (all Macs, no Homebrew needed)

Find where uvx actually lives:

which uvx

Common outputs:

• Homebrew Apple Silicon: /opt/homebrew/bin/uvx
• Homebrew Intel: /usr/local/bin/uvx
• curl installer: /Users/yourname/.local/bin/uvx

Use that full path as "command" in the config:

{
  "mcpServers": {
    "tooluniverse": {
      "command": "/Users/yourname/.local/bin/uvx",
      "args": ["--refresh", "tooluniverse"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Replace /Users/yourname/.local/bin/uvx with the actual output of which uvx.

---

Fix C — Symlink (Linux / advanced)

sudo ln -sf "$(which uvx)" /usr/local/bin/uvx

---

Writing the Config

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Use the one-liner to safely create or merge without overwriting existing servers:

python3 -c "
import json, os
p = os.path.expanduser('~/Library/Application Support/Claude/claude_desktop_config.json')
os.makedirs(os.path.dirname(p), exist_ok=True)
cfg = json.load(open(p)) if os.path.exists(p) else {}
cfg.setdefault('mcpServers', {})['tooluniverse'] = {
    'command': 'uvx', 'args': ['--refresh', 'tooluniverse'],
    'env': {'PYTHONIOENCODING': 'utf-8'}
}
json.dump(cfg, open(p, 'w'), indent=2)
print('Done:', p)
"

If the user installed uv via curl (not Homebrew), replace 'command': 'uvx' with 'command': '/Users/yourname/.local/bin/uvx' using their actual path from which uvx.

Restarting Claude Desktop

Use ⌘Q (not just closing the window) to fully quit, then reopen.

⏱️ First launch takes 60–90 seconds while Claude Desktop downloads and installs ToolUniverse.

Verifying MCP Tools Are Loaded

Claude Desktop's UI for MCP tools has changed across versions — look for whichever of these appears in your chat input bar:

• Newer versions: A "Search and tools" button (or a + icon) at the bottom of the chat input. Click it → you should see tooluniverse listed under connected tools/connectors. You can toggle it on/off from here.
• Older versions: A 🔨 hammer icon in the bottom-right of the chat input. Click it to see the list of available tools from tooluniverse.

If neither appears, check Settings → Developer → MCP Servers — it shows each server's connection status and any error messages.

Verifying in the Logs

While Claude Desktop is loading, monitor the MCP logs:

tail -f ~/Library/Logs/Claude/mcp*.log          # macOS
tail -f ~/.config/Claude/logs/mcp*.log          # Linux

Look for "tooluniverse" connected — that confirms it worked.

Common error messages and what they mean:

• ENOENT / spawn uvx ENOENT → uvx not found; use absolute path or Homebrew fix
• spawn /Users/you/.local/bin/uvx ENOENT → wrong absolute path; run which uvx again
• exit 1 immediately → run uvx tooluniverse --help in terminal to see the actual error

Installing Skills (Required)

Skills are required for ToolUniverse to work as an intelligent research assistant. Run in terminal:

Option A — npx (quickest):

npx skills add mims-harvard/ToolUniverse --all

If npx is not found, install Node.js from nodejs.org (LTS version includes npx), then retry.

Option B — git clone (if npx fails):

git clone --depth 1 --filter=blob:none --sparse https://github.com/mims-harvard/ToolUniverse.git /tmp/tu-skills
cd /tmp/tu-skills && git sparse-checkout set skills
# macOS — adjust path for Linux (~/.config/Claude/skills/) or Windows (%APPDATA%\Claude\skills\)
mkdir -p ~/Library/Application\ Support/Claude/skills && cp -r /tmp/tu-skills/skills/* ~/Library/Application\ Support/Claude/skills/
rm -rf /tmp/tu-skills

Verifying Skills Are Installed

After running npx skills add, check the terminal output — it prints the exact directory where skills were installed. Use that path to verify:

ls <path-from-npx-output> | grep tooluniverse

If the output didn't show the path, the default location for Claude Desktop varies by OS:

• macOS: ~/Library/Application Support/Claude/skills/
• Linux: ~/.config/Claude/skills/
• Windows: %APPDATA%\Claude\skills\

# macOS example:
ls ~/Library/Application\ Support/Claude/skills | grep tooluniverse

✅ Pass: You see folders like tooluniverse, tooluniverse-drug-research, etc. → skills are ready. ❌ Fail: Nothing listed → wrong directory or install didn't complete. Check SKILLS_CATALOG.md and retry.

Smoke test — in Claude Desktop, say:

"Use the tooluniverse skill to research the drug metformin"

If the response is plain text with no tool calls, skills are not in the right directory.

Setup ToolUniverse - Usage Examples

Real-world examples of using the setup-tooluniverse skill.

Example 1: First-Time Setup for Cursor

User Request: "I want to use ToolUniverse in Cursor"

Agent Response:

1. Check Prerequisites

   python scripts/check_prerequisites.py

Output shows:

• ✓ Python 3.12 (compatible)
• ✓ pip available
• ✓ uv available
• ✓ Cursor config found

2. Install ToolUniverse

   pip install tooluniverse

3. Verify Installation

   python scripts/verify_installation.py

Output shows:

• ✓ Import successful (v1.0.17)
• ✓ Loaded 764 tools
• ✓ CLI commands available

4. Configure MCP

Create ~/Library/Application Support/Cursor/User/mcp.json:

   {
     "mcpServers": {
       "tooluniverse": {
         "command": "tooluniverse-smcp-stdio",
         "args": ["--compact-mode"]
       }
     }
   }

5. Test Configuration

   python scripts/test_mcp_connection.py

Output shows:

• ✓ Config found and valid
• ✓ ToolUniverse configured
• ✓ Compact mode enabled
• ✓ Command available

6. Restart Cursor and verify MCP server appears

Example 2: Troubleshooting Installation

User Request: "ToolUniverse isn't working in Cursor"

Agent Response:

1. Run Diagnostics

   python scripts/diagnose_setup.py

Report identifies issues:

• ❌ tooluniverse-smcp-stdio not found in PATH
• ⚠️ Multiple Python installations detected

2. Fix PATH Issue

   # Find where pip installed scripts
   python -m pip show tooluniverse | grep Location
   
   # Add to PATH in ~/.zshrc or ~/.bashrc
   export PATH="$HOME/.local/bin:$PATH"
   
   # Reload shell
   source ~/.zshrc

3. Verify Fix

   which tooluniverse-smcp-stdio
   # Should show: /Users/username/.local/bin/tooluniverse-smcp-stdio

4. Retest

   python scripts/verify_installation.py
   # Should now show all checks passing

Example 3: Development Setup

User Request: "I'm developing ToolUniverse tools and need to test them"

Agent Response:

1. Clone Repository

   git clone https://github.com/mims-harvard/ToolUniverse.git
   cd ToolUniverse

2. Install in Development Mode

   pip install -e .

3. Configure MCP for Development

In mcp.json:

   {
     "mcpServers": {
       "tooluniverse-dev": {
         "command": "python3",
         "args": [
           "-m",
           "tooluniverse.smcp_server",
           "--compact-mode",
           "--verbose"
         ],
         "cwd": "/path/to/ToolUniverse"
       }
     }
   }

4. Verify Development Setup

   python scripts/verify_installation.py

Shows development version is active

Example 4: Context Overflow Issue

User Request: "Cursor is super slow and keeps erroring when ToolUniverse loads"

Agent Response:

Diagnosis: Not using compact mode, causing context overflow.

1. Check Current Config

   python scripts/test_mcp_connection.py

Output shows:

• ⚠️ Compact mode NOT enabled

2. Fix Configuration

Update mcp.json to add --compact-mode:

   {
     "mcpServers": {
       "tooluniverse": {
         "command": "tooluniverse-smcp-stdio",
         "args": ["--compact-mode"]  // ← Add this
       }
     }
   }

3. Restart Cursor

4. Verify Fix

• MCP server should load quickly
• Only 5 tools shown in tool list
• Can still execute all 764+ tools via execute_tool

Example 5: Specific Tool Categories

User Request: "I only need protein and chemistry tools"

Agent Response:

1. List Available Categories

   python scripts/list_tool_categories.py

Shows categories like:

• UniProt (45 tools)
• ChEMBL (38 tools)
• PDB (25 tools)
• etc.

2. Configure Specific Categories

In mcp.json:

   {
     "mcpServers": {
       "tooluniverse": {
         "command": "tooluniverse-smcp-stdio",
         "args": [
           "--categories",
           "UniProt",
           "ChEMBL",
           "PDB"
         ]
       }
     }
   }

3. Restart and Verify

Note: Even with specific categories, may cause context issues. Compact mode still recommended.

Example 6: UV Installation for Better Isolation

User Request: "I want to keep ToolUniverse isolated from my other Python projects"

Agent Response:

1. Install UV

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create Dedicated Environment

   mkdir -p ~/tooluniverse-env
   cd ~/tooluniverse-env
   uv pip install tooluniverse

3. Configure MCP with UV

In mcp.json:

   {
     "mcpServers": {
       "tooluniverse": {
         "command": "uv",
         "args": [
           "--directory",
           "/Users/username/tooluniverse-env",
           "run",
           "tooluniverse-smcp-stdio",
           "--compact-mode"
         ]
       }
     }
   }

4. Test

   python scripts/test_mcp_connection.py

Example 7: Python Version Incompatibility

User Request: "Getting error about Python version"

Agent Response:

1. Check Version

   python3 --version
   # Output: Python 3.9.7

Problem: ToolUniverse requires 3.10-3.13

2. Install Compatible Python

macOS:

   brew install python@3.12

Ubuntu:

   sudo apt install python3.12 python3.12-pip

3. Install with Specific Version

   python3.12 -m pip install tooluniverse

4. Update MCP Config

If needed, specify Python version:

   {
     "mcpServers": {
       "tooluniverse": {
         "command": "python3.12",
         "args": [
           "-m",
           "tooluniverse.smcp_server",
           "--compact-mode"
         ]
       }
     }
   }

Example 8: Windows Setup

User Request: "Setting up on Windows 11"

Agent Response:

1. Check Prerequisites (PowerShell)

   python --version
   # Should show 3.10-3.13
   
   pip --version

2. Install ToolUniverse

   pip install tooluniverse

3. Find Config Location

   %APPDATA%\Cursor\User\mcp.json

4. Create Config

   {
     "mcpServers": {
       "tooluniverse": {
         "command": "tooluniverse-smcp-stdio",
         "args": ["--compact-mode"]
       }
     }
   }

5. Test (PowerShell)

   python scripts/verify_installation.py

Example 9: API Keys Configuration

User Request: "Some tools need API keys, how do I configure them?"

Agent Response:

1. Check Which Tools Need Keys

Most tools don't need API keys. Optional ones:

• OpenAI/Anthropic: For agentic tools
• UMLS: For medical terminology

2. Configure via Environment

Create .env file in project:

   OPENAI_API_KEY=sk-...
   ANTHROPIC_API_KEY=sk-ant-...
   UMLS_API_KEY=your-key

3. Or Configure in MCP

In mcp.json:

   {
     "mcpServers": {
       "tooluniverse": {
         "command": "tooluniverse-smcp-stdio",
         "args": ["--compact-mode"],
         "env": {
           "OPENAI_API_KEY": "sk-...",
           "UMLS_API_KEY": "your-key"
         }
       }
     }
   }

Security Note: Don't commit API keys to git!

Example 10: Complete Fresh Setup

User Request: "Walk me through complete setup from scratch"

Agent Response:

# 1. Check prerequisites
cd ~/.cursor/skills/setup-tooluniverse
python scripts/check_prerequisites.py

# 2. Install ToolUniverse
pip install tooluniverse

# 3. Verify installation
python scripts/verify_installation.py

# 4. Create MCP config
cat > ~/Library/Application\ Support/Cursor/User/mcp.json << 'EOF'
{
  "mcpServers": {
    "tooluniverse": {
      "command": "tooluniverse-smcp-stdio",
      "args": ["--compact-mode"]
    }
  }
}
EOF

# 5. Test configuration
python scripts/test_mcp_connection.py

# 6. Restart Cursor (manual step)

# 7. Verify in Cursor
# - Check MCP servers list
# - Try: list_tools
# - Try: grep_tools with keyword "protein"

Expected Timeline: 5-10 minutes total

Common Error Messages and Solutions

"Command not found: tooluniverse-smcp-stdio"

Solution: Scripts directory not in PATH

pip install --force-reinstall tooluniverse
# or add to PATH: export PATH="$HOME/.local/bin:$PATH"

"requires-python = '>=3.10'"

Solution: Python version too old

# Install compatible Python
brew install python@3.12  # macOS
# or download from python.org

"ModuleNotFoundError: No module named 'tooluniverse'"

Solution: Not installed or wrong Python

# Verify installation
pip show tooluniverse

# If not installed
pip install tooluniverse

"Context window overflow" or slow performance

Solution: Enable compact mode

"args": ["--compact-mode"]  // Add to mcp.json

"Directory not found" (uv configs)

Solution: Create directory

mkdir -p ~/tooluniverse-env
cd ~/tooluniverse-env
uv pip install tooluniverse

Reporting a ToolUniverse Issue

Use this when the user is stuck and the Common Issues table hasn't resolved the problem.

Agent: Compose the Issue Body

You have all the context from the conversation. Fill in the template below — do not ask the user to run any commands.

Title: [one-line summary, e.g. "Trae: tooluniverse MCP server not appearing after restart"]

**Client**: [Cursor / Trae / Claude Desktop / VS Code / Windsurf / etc.]
**OS**: [Windows 11 / macOS 14 / Ubuntu 22.04 — be specific]
**uv version**: [from Step 1 output earlier, or "unknown"]
**ToolUniverse version**: [from `uvx tooluniverse --version` output, or "unknown"]

**What I did**
1. [first step the user took]
2. [second step]
3. [etc.]

**Error message**

[paste the exact error text here, or write "no error shown — server just doesn't appear"]

**What I expected**
[e.g. "tooluniverse to appear in the MCP servers list after restarting the app"]

**What was already tried**
- [fix 1 attempted and result]
- [fix 2 attempted and result]

Once composed, output the filled issue body and then give the user the walkthrough below.

---

Walk the User Through GitHub

Say this to the user (adapt the language to match how they've been communicating):

"I've prepared the issue report below — you just need to copy and paste it. Here's how to submit it, step by step:

>

Step 1. Open this link in your browser:

https://github.com/mims-harvard/ToolUniverse/issues/new

>

Step 2. Sign in to GitHub. If you don't have an account, click "Sign up" — it's free and takes about a minute (no credit card needed). You can also sign up with Google.

>

Step 3. You'll see a form with two fields:

- Title — paste the one-line title from the report I prepared

- Leave a comment (the large text box) — paste the full report body

>

Step 4. Scroll down and click the green "Submit new issue" button.

>

That's it! The team usually replies within 1–2 days. You'll get an email notification when they respond — no need to check back manually."

---

Email Fallback

If the user is not comfortable with GitHub or can't create an account, they can send the same issue body by email:

shanghuagao@gmail.com

Subject line: ToolUniverse setup issue: [one-line summary]

ToolUniverse Installation Guide

Detailed installation options and troubleshooting.

Installation Methods

Method 1: PyPI (Recommended for Users)

Standard installation from Python Package Index:

pip install tooluniverse

Pros: Simple, stable, latest release Cons: May not have cutting-edge features

Method 2: UV (Recommended for MCP)

Installation with uv package manager for better isolation:

# Install uv first
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create dedicated environment
mkdir -p ~/tooluniverse-env
cd ~/tooluniverse-env

# Install ToolUniverse
uv pip install tooluniverse

Pros: Better isolation, faster dependency resolution, works well with MCP Cons: Requires uv installation

Method 3: Development (For Contributors)

Install from source for development:

git clone https://github.com/mims-harvard/ToolUniverse.git
cd ToolUniverse
pip install -e .

Pros: Latest features, can modify code Cons: May have bugs, requires git

Optional Dependencies

All Features

pip install tooluniverse[all]

Specific Features

# Single-cell analysis
pip install tooluniverse[singlecell]

# Machine learning and embeddings
pip install tooluniverse[ml,embedding]

# Visualization tools
pip install tooluniverse[visualization]

# Graph analysis
pip install tooluniverse[graph]

# Bioinformatics tools
pip install tooluniverse[bioinformatics]

# Development tools
pip install tooluniverse[dev]

Python Version Requirements

• Required: Python 3.10 - 3.13
• Not supported: Python <3.10 or >=3.14

Installing Specific Python Version

macOS (Homebrew)

brew install python@3.12
python3.12 -m pip install tooluniverse

Ubuntu/Debian

sudo apt update
sudo apt install python3.12 python3.12-pip
python3.12 -m pip install tooluniverse

Windows

Download from python.org and select version 3.12.

Virtual Environment (Recommended)

Create isolated environment:

# Create virtual environment
python3 -m venv tooluniverse-venv

# Activate
source tooluniverse-venv/bin/activate  # macOS/Linux
# or
tooluniverse-venv\Scripts\activate  # Windows

# Install
pip install tooluniverse

Verification

After installation, verify:

# Check installation
pip show tooluniverse

# Test import
python3 -c "from tooluniverse import ToolUniverse; print('✓ Import successful')"

# Check CLI commands
which tooluniverse-smcp-stdio

Common Installation Issues

Issue: pip not found

# macOS/Linux
python3 -m ensurepip --upgrade

# Windows
py -m ensurepip --upgrade

Issue: Permission denied

# Use user installation
pip install --user tooluniverse

# Or use virtual environment (recommended)

Issue: SSL certificate error

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org tooluniverse

Issue: Outdated pip

pip install --upgrade pip
pip install tooluniverse

Uninstallation

pip uninstall tooluniverse

To remove all data:

# Remove cache (if exists)
rm -rf ~/.cache/tooluniverse

Upgrading

pip install --upgrade tooluniverse

Platform-Specific Notes

macOS

• Use Homebrew Python recommended
• May need Xcode Command Line Tools: xcode-select --install

Windows

• Use official Python installer
• Add Python to PATH during installation
• May need Microsoft C++ Build Tools for some dependencies

Linux

• Most distros work out of the box
• May need python3-dev package for compiling dependencies

MCP Configuration Guide

Advanced configuration options for ToolUniverse MCP integration.

Configuration File Locations

Cursor

• Global (all workspaces) — macOS/Linux: ~/.cursor/mcp.json · Windows: %USERPROFILE%\.cursor\mcp.json
• Project-level (single workspace): .cursor/mcp.json in the project root — can be committed to version control for team sharing

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

VS Code / Copilot

• Project-level (workspace root): .vscode/mcp.json
• Note: VS Code uses "servers" key (not "mcpServers") and requires "type": "stdio" — see the VS Code template below.

Windsurf

• macOS/Linux: ~/.codeium/windsurf/mcp_config.json
• Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Claude Code

• Global: ~/.claude.json
• Project-level: .mcp.json in the project root

Gemini CLI

• ~/.gemini/settings.json

Antigravity

• macOS/Linux: ~/.gemini/antigravity/mcp_config.json
• Windows: %USERPROFILE%\.gemini\antigravity\mcp_config.json

Access via: Agent Panel → "..." → Manage MCP Servers → View raw config. Uses "mcpServers" key (same as Claude Desktop format).

Cline

Full path to cline_mcp_settings.json varies by OS:

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Cline CLI (standalone): ~/.cline/data/settings/cline_mcp_settings.json

Access via Cline's "MCP Servers" icon → Configure tab → "Configure MCP Servers". Uses "mcpServers" key (same as Claude Desktop format).

Trae

• Windows: %APPDATA%\Trae\User\mcp.json
• macOS: ~/Library/Application Support/Trae/User/mcp.json
• Linux: ~/.config/Trae/User/mcp.json

Verify the exact path in Trae: Settings → MCP → Open config file.

The AI agent can only access the global config. Project-level .trae/mcp.json is an experimental/beta feature and is not accessible to the agent — do not use it for MCP server registration.

For full Trae setup instructions (including manual write fallback and verification), see TRAE.md.

Configuration Templates

Basic Configuration (Recommended)

Zero-install setup using uvx (auto-downloads and runs ToolUniverse):

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

--refresh keeps ToolUniverse auto-updated on each startup (~1–2s overhead). Remove it to pin to the cached version and update manually with uv cache clean tooluniverse.

pip-Based Configuration (Alternative)

If you have ToolUniverse installed via pip install tooluniverse, you can use the installed command directly:

{
  "mcpServers": {
    "tooluniverse": {
      "command": "tooluniverse-smcp-stdio",
      "args": ["--compact-mode"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Development Configuration

Using development installation:

{
  "mcpServers": {
    "tooluniverse": {
      "command": "python3",
      "args": [
        "-m",
        "tooluniverse.smcp_server",
        "--compact-mode"
      ],
      "cwd": "/path/to/ToolUniverse-main"
    }
  }
}

VS Code / Copilot Configuration

VS Code uses a different schema. Create .vscode/mcp.json in the workspace root:

{
  "servers": {
    "tooluniverse": {
      "command": "uvx",
      "args": ["--refresh", "tooluniverse"],
      "env": { "PYTHONIOENCODING": "utf-8" },
      "type": "stdio"
    }
  }
}

Key differences from standard config: uses "servers" (not "mcpServers") and requires "type": "stdio". After saving, fully restart VS Code and open Copilot Chat in that workspace.

Configuration Options

Compact Mode (Default with uvx)

When using uvx tooluniverse, compact mode is enabled by default — no flag needed. It exposes only 5 core tools to prevent context overflow, while keeping all 1000+ tools accessible via execute_tool.

If using the pip-based tooluniverse-smcp-stdio command, pass --compact-mode explicitly:

"args": ["--compact-mode"]

Core tools exposed in compact mode:

• list_tools - List all available tools
• grep_tools - Search tools by keyword
• get_tool_info - Get tool details
• execute_tool - Execute any tool by name
• find_tools - Find tools by description

Specific Categories

Load only specific tool categories:

"args": [
  "--categories",
  "uniprot",
  "ChEMBL",
  "opentarget",
  "pdb"
]

Available categories: Run uvx tooluniverse --list-categories to see all.

Warning: Multiple categories may still cause context issues.

Exclude Categories

Load all except specific categories:

"args": [
  "--exclude-categories",
  "mcp_auto_loader_boltz",
  "mcp_auto_loader_expert_feedback"
]

Specific Tools Only

Load only named tools:

"args": [
  "--include-tools",
  "UniProt_get_entry_by_accession",
  "ChEMBL_get_molecule_by_chembl_id"
]

Enable Hooks

Enable output processing hooks (disabled by default for stdio):

"args": [
  "--refresh", "tooluniverse",
  "--hooks",
  "--hook-type",
  "SummarizationHook"
]

Hook types:

• SummarizationHook - Summarize long outputs
• FileSaveHook - Save outputs to files

Verbose Logging

Enable detailed logging for debugging:

"args": [
  "--refresh", "tooluniverse",
  "--verbose"
]

Environment Variables

Standard Variables

"env": {
  "PYTHONIOENCODING": "utf-8",
  "PYTHONPATH": "/custom/python/path",
  "TOOLUNIVERSE_CACHE_DIR": "/custom/cache/dir"
}

API Keys

For tools requiring authentication:

"env": {
  "PYTHONIOENCODING": "utf-8",
  "OPENAI_API_KEY": "your-key-here",
  "ANTHROPIC_API_KEY": "your-key-here",
  "UMLS_API_KEY": "your-key-here"
}

Security Note: Avoid hardcoding keys. Use environment variables or .env files.

Better API Key Management

Use environment variables from shell:

"env": {
  "PYTHONIOENCODING": "utf-8",
  "OPENAI_API_KEY": "${OPENAI_API_KEY}"
}

Then set in shell:

export OPENAI_API_KEY=your-key-here

Multiple MCP Servers

Configure multiple servers:

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

Working Directory

Specify working directory:

{
  "mcpServers": {
    "tooluniverse": {
      "command": "uvx",
      "args": ["--refresh", "tooluniverse"],
      "env": { "PYTHONIOENCODING": "utf-8" },
      "cwd": "/path/to/working/directory"
    }
  }
}

Testing Configuration

Validate JSON

Before saving, validate JSON syntax:

# macOS/Linux
cat mcp.json | python3 -m json.tool

# Or use online validator

Test Command Directly

Test the MCP command in terminal:

uvx tooluniverse --help
# Should print usage text without errors

Test with a ToolUniverse Skill

After skills are installed (see SKILL.md Step 6), verify end-to-end by invoking the tooluniverse router skill in your prompt:

"Use the tooluniverse skill to research the drug metformin"

The tooluniverse skill is a router — it automatically picks the right sub-skill and calls multiple tools. Mentioning it explicitly ensures it activates on any client, since not all clients auto-detect skills from natural language alone.

If the response comes back as plain text without any tool calls, either skills are not installed, they are in the wrong directory, or the MCP server is not connected.

Other examples:

• "Use the tooluniverse skill: what is known about Alzheimer's disease?"
• "Use the tooluniverse skill: what does the literature say about CRISPR in cancer?"

Check Logs

After restarting application, check logs:

Cursor logs:

• macOS: ~/Library/Application Support/Cursor/logs/
• Look for files with "mcp" in the name

Claude Desktop logs:

• Access via app: Help → View Logs

Troubleshooting Configuration

Issue: Server Won't Start

1. Test command directly in terminal 2. Check JSON syntax (no trailing commas) 3. Verify paths are absolute, not relative 4. Check file permissions

Issue: Context Overflow

• Ensure --compact-mode is in args
• Reduce number of categories
• Use specific tools only

Issue: Command Not Found

• Verify uvx works: uvx --version
• Test ToolUniverse directly: uvx tooluniverse --help
• If uvx is missing, install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
• For pip-based installs: pip show tooluniverse and which tooluniverse-smcp-stdio

Issue: Environment Variables Not Working

• Use absolute paths
• Avoid ~ expansion (use full path)
• Check variable syntax in JSON

Performance Optimization

Fast Startup

Use minimal categories (compact mode is already the default):

"args": [
  "--refresh", "tooluniverse",
  "--categories",
  "special_tools"
]

Memory Optimization

Exclude heavy categories:

"args": [
  "--refresh", "tooluniverse",
  "--exclude-categories",
  "mcp_auto_loader_boltz"
]

Security Considerations

1. API Keys: Never commit config files with hardcoded keys 2. Paths: Use absolute paths to avoid ambiguity 3. Permissions: Restrict config file permissions (chmod 600) 4. Validation: Always validate JSON before saving

Example Configurations

Research Use Case

For scientific research with common tools:

{
  "mcpServers": {
    "tooluniverse": {
      "command": "uvx",
      "args": ["--refresh", "tooluniverse"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "NCBI_API_KEY": "your-key-here"
      }
    }
  }
}

Development Use Case

For tool development and testing:

{
  "mcpServers": {
    "tooluniverse-dev": {
      "command": "python3",
      "args": [
        "-m",
        "tooluniverse.smcp_server",
        "--compact-mode",
        "--verbose"
      ],
      "cwd": "/path/to/ToolUniverse-main"
    }
  }
}

Production Use Case

For production with specific tool categories:

{
  "mcpServers": {
    "tooluniverse-prod": {
      "command": "uvx",
      "args": [
        "tooluniverse",
        "--categories",
        "uniprot",
        "ChEMBL",
        "opentarget"
      ],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

Advanced Features

Space Configuration

Load preset tool configurations:

"args": [
  "--compact-mode",
  "--load",
  "community/proteomics-toolkit"
]

Custom Hook Configuration

Use custom hook configuration file:

"args": [
  "--compact-mode",
  "--hooks",
  "--hook-config-file",
  "/path/to/hook_config.json"
]

MCP Configuration — Special Formats

Most clients use the standard mcpServers JSON format (see SKILL.md). These clients use different formats:

VS Code (Copilot)

Uses "servers" key (not "mcpServers") and requires "type" field. Add to .vscode/mcp.json:

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

Codex (TOML format)

Add to ~/.codex/config.toml:

[mcp_servers.tooluniverse]
command = "uvx"
args = ["tooluniverse"]
env = { "PYTHONIOENCODING" = "utf-8" }

OpenCode

Uses mcp key with type and command as array in opencode.json:

{
  "mcp": {
    "tooluniverse": {
      "type": "local",
      "command": ["uvx", "tooluniverse"],
      "enabled": true,
      "environment": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

Antigravity

Standard mcpServers format. Access via: "..." dropdown → Manage MCP Servers → View raw config.

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

ToolUniverse Skills Catalog

65+ pre-built research workflows. Skills activate automatically when the AI detects a relevant request, or trigger them explicitly (e.g., "Use the tooluniverse skill to research the drug aspirin").

Research Skills

Data Retrieval Skills

Clinical Skills

Drug Discovery Skills

Genomics & Omics Skills

Transcriptomics & Proteomics Skills

Systems Biology & Other Skills

How to Install

npx skills add mims-harvard/ToolUniverse --all

Or manually clone and copy to your client's skills directory:

Trae IDE Setup

Use your system terminal — not Trae's built-in terminal.

Trae may run in a sandboxed environment. All installation commands (uv, npx, git) must be run in your OS terminal (Windows: PowerShell or Command Prompt; macOS/Linux: Terminal app). Commands run inside Trae's terminal panel may appear to succeed but Trae won't find the tools after restart.

---

Step 1: Install uvx

Open your system terminal (not Trae's terminal) and check if uv is already installed:

uvx --version

If the command is not found, install uv:

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.zshrc 2>/dev/null || source ~/.bashrc 2>/dev/null

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Then close and reopen PowerShell so the new uvx command is available.

Verify ToolUniverse loads:

uvx tooluniverse --help

This should print help text. If it fails, see TROUBLESHOOTING.md.

⏸️ Ask: "Does uvx tooluniverse --help print help text in your system terminal?" Wait before continuing.

---

Step 2: Set Up Global Config

Trae's global MCP config is the only config the AI agent can access.

Find the config path: Open Trae → Settings → MCP (or "..." menu → Open MCP config).

Expected locations by OS:

• Windows: %APPDATA%\Trae\User\mcp.json (e.g. C:\Users\yourname\AppData\Roaming\Trae\User\mcp.json)
• macOS: ~/Library/Application Support/Trae/User/mcp.json
• Linux: ~/.config/Trae/User/mcp.json

⏸️ Ask: "Can you open Trae Settings → MCP and confirm the config file path it shows?" Confirm before continuing.

Config JSON

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

Option A — Python one-liner (try first, run in system terminal)

Replace CONFIG_PATH with the confirmed path:

python3 -c "
import json, os
p = r'CONFIG_PATH'
os.makedirs(os.path.dirname(p), exist_ok=True)
cfg = json.load(open(p)) if os.path.exists(p) else {}
cfg.setdefault('mcpServers', {})['tooluniverse'] = {
    'command': 'uvx', 'args': ['--refresh', 'tooluniverse'],
    'env': {'PYTHONIOENCODING': 'utf-8'}
}
json.dump(cfg, open(p, 'w'), indent=2)
print('Done:', p)
"

Option B — Trae Settings UI (recommended if Option A fails)

Trae has a built-in MCP configuration panel that bypasses file permission issues:

1. Press Ctrl U (or click the Agents icon) to open the Agents panel 2. Click the AI Management gear icon → MCP → Configure Manually 3. Paste the full JSON block above into the text field 4. Click Confirm 5. Restart Trae fully

⏸️ Ask: "Did tooluniverse appear in the MCP panel after restarting?" Wait before continuing.

Option C — Direct file paste (last resort)

If both Options A and B fail:

1. Open the global config file in a text editor (Notepad, VS Code, etc.) at the path confirmed above 2. If the file is empty or missing, paste the full JSON block above 3. If the file already has content, add the "tooluniverse" block inside the existing "mcpServers" object 4. Save the file 5. Restart Trae fully

⏸️ Ask: "Did the config get written? Do you see tooluniverse in Settings → MCP?" Wait before continuing.

⚠️ Do Not Use Project-Level Config

.trae/mcp.json is an experimental/beta feature. The agent cannot access project-level MCP servers. If Trae shows an "Enable Project MCP" option — ignore it. Always use the global config path.

---

Step 3: Install Skills

Skills are required for ToolUniverse to work as an intelligent research assistant. Run these in your system terminal.

Option A — npx (quickest)

npx skills add mims-harvard/ToolUniverse --all

If npx is not found, install Node.js from nodejs.org (the LTS version includes npm and npx), then retry.

Option B — git clone (if npx fails: corporate network, cert issues, or proxy problems)

If git is not found, install it from git-scm.com, then retry.

macOS / Linux:

git clone --depth 1 --filter=blob:none --sparse https://github.com/mims-harvard/ToolUniverse.git /tmp/tu-skills
cd /tmp/tu-skills && git sparse-checkout set skills
mkdir -p ~/.trae/skills && cp -r /tmp/tu-skills/skills/* ~/.trae/skills/
rm -rf /tmp/tu-skills

Windows (PowerShell — run each line separately):

# Run each line separately — PowerShell does not support && like bash
git clone --depth 1 --filter=blob:none --sparse https://github.com/mims-harvard/ToolUniverse.git "$env:TEMP\tu-skills"
Set-Location "$env:TEMP\tu-skills"
git sparse-checkout set skills
New-Item -ItemType Directory -Force "$env:APPDATA\Trae\skills" | Out-Null
robocopy "$env:TEMP\tu-skills\skills" "$env:APPDATA\Trae\skills" /E
Remove-Item -Recurse -Force "$env:TEMP\tu-skills"

Note: The exact skills directory for Trae may vary. Check SKILLS_CATALOG.md if skills don't activate after installation.

Verify skills were installed — run in your system terminal:

macOS / Linux:

ls ~/.trae/skills | grep tooluniverse

Windows (PowerShell):

Get-ChildItem "$env:APPDATA\Trae\skills" | Where-Object { $_.Name -like "*tooluniverse*" }

✅ Pass: You see folders like tooluniverse, tooluniverse-drug-research, etc. → proceed to Step 4. ❌ Fail: Nothing listed → the install didn't complete or went to the wrong directory. Re-run the install command or try the git clone option.

⏸️ Ask: "Do you see tooluniverse skill folders listed?" Wait before continuing.

---

Step 4: Restart and Test

1. Fully quit Trae (not just close the window), then reopen it 2. First launch takes 60–90 seconds while Trae downloads ToolUniverse in the background

Check MCP connection: Open Trae Settings → MCP. tooluniverse should appear with a green/connected status.

Live tool test (verifies MCP is working):

list_tools

or

execute_tool("PubMed_search_articles", {"query": "CRISPR", "max_results": 1})

Skills smoke test (verifies skills are installed):

Say: "Use the tooluniverse skill to research the drug metformin"

The tooluniverse skill is a router — it picks the right sub-skill automatically. If the response is plain text with no tool calls, skills are not installed or not in the correct directory.

If something is still broken, check: 1. The config file is at the correct global path (not .trae/mcp.json) 2. uvx tooluniverse --help works in your system terminal (not Trae's terminal) 3. Trae was fully restarted 4. Fetch TROUBLESHOOTING.md for more diagnostics, or GITHUB_ISSUE.md to report the issue.

Troubleshooting ToolUniverse Setup

When something fails, always provide the exact copy-paste fix command — don't just say "check the logs."

Issue 1: Python Version Incompatibility

Symptom: Error containing requires-python = ">=3.10" or Python 3.9 is not supported

Fix:

brew install python@3.12        # macOS
# or: sudo apt install python3.12  # Ubuntu/Debian
python3.12 -m pip install tooluniverse

Issue 2: uvx or uv Not Found

Symptom: uvx: command not found or uv: command not found

Fix:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.zshrc 2>/dev/null || source ~/.bashrc 2>/dev/null
uvx --version   # verify it worked

Issue 3: Context Window Overflow

Symptom: MCP server loads but the client becomes very slow, or gives "context too large" errors

Note: Compact mode is already the default — the tooluniverse entry point enables it automatically. If still hitting context limits:

"args": ["--refresh", "tooluniverse", "--tool-categories", "uniprot,chembl,pubmed"]

Restart the app after editing.

Issue 4: Import Errors for Specific Tools

Symptom: Tool fails with ModuleNotFoundError: No module named 'rdkit' (or similar)

Fix:

pip install tooluniverse[all]
# Or the specific extra needed:
# pip install tooluniverse[visualization]   # rdkit, py3Dmol
# pip install tooluniverse[singlecell]       # cellxgene
# pip install tooluniverse[ml,embedding]     # sentence-transformers, admet-ai

Issue 5: MCP Server Won't Start

Symptom: No tooluniverse server in client's server list, "Failed to spawn process", "ENOENT", "command not found"

#1 most common cause — GUI apps (Claude Desktop, Windsurf) don't inherit shell PATH.

Option A — Homebrew (macOS, recommended, permanent):

brew install uv
# Then restart the app — can now use "uvx" everywhere, no absolute path needed

Option B — Symlink (macOS/Linux, permanent):

sudo ln -sf "$(which uvx)" /usr/local/bin/uvx   # Intel Mac / Linux
# OR for Apple Silicon Mac:
sudo ln -sf "$(which uvx)" /opt/homebrew/bin/uvx

Option C — Absolute path (all platforms, quick fix):

which uvx   # macOS/Linux → e.g. /opt/homebrew/bin/uvx or /Users/you/.local/bin/uvx
where uvx   # Windows

Use that full path as "command" in your config instead of "uvx".

Full diagnostic chain — run these in order:

# 1. Can uvx find and run it?
uvx tooluniverse --help

# 2. Does it start without errors? (Ctrl+C to stop)
uvx tooluniverse

# 3. Is the config file valid JSON?
python3 -m json.tool ~/.cursor/mcp.json   # replace path for your client

# 4. View the client's MCP logs
tail -50 ~/Library/Logs/Claude/mcp*.log 2>/dev/null        # Claude Desktop (macOS)
tail -50 ~/Library/Application\ Support/Cursor/logs/*.log  # Cursor (macOS)

Fix based on where the chain breaks. Other common causes: trailing commas in JSON, wrong config file path.

Issue 6: API Key Errors (401/403)

Symptom: Tool returns "unauthorized", "forbidden", or "invalid API key"

Diagnostic:

echo $NCBI_API_KEY    # replace with the failing key name

Common fixes:

• Keys must be in the "env" block in your MCP config file (not a .env file the app doesn't load):

  "env": { "PYTHONIOENCODING": "utf-8", "NCBI_API_KEY": "your_key_here" }

• Wrong key name: variable must match exactly (e.g., ONCOKB_API_TOKEN not ONCOKB_API_KEY)
• Restart required after editing the config file
• Free tier pending: DisGeNET and OMIM may take 24–48h for account approval

Issue 7: Upgrading ToolUniverse

Symptom: User wants a newer version, or tools are missing / behavior is outdated

The recommended config uses "--refresh" which auto-updates on every launch. If the user's config doesn't have it:

"args": ["--refresh", "tooluniverse"]

To upgrade immediately:

uv cache clean tooluniverse   # clears uvx cache, then restart the MCP client

To pin a specific version:

"args": ["tooluniverse==1.0.19"]

For pip users:

pip install --upgrade tooluniverse

Issue 8: Python Version Too New

Symptom: Errors like requires-python >=3.10,<3.14, SyntaxError in ToolUniverse code, or ModuleNotFoundError for a built-in module after upgrading Python.

ToolUniverse supports Python 3.10–3.13. Python 3.14+ (pre-release) may break things.

Check your Python version:

python3 --version
uvx tooluniverse --help   # see what Python uvx picks up

Fix — pin to a compatible Python for uvx:

uvx --python 3.12 tooluniverse --help

If that works, update your MCP config to use the pinned version:

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

Issue 9: Stale or Broken Package Version

Symptom: A tool that used to work now errors, or a new tool listed in docs isn't available, or you see AttributeError / ImportError referencing ToolUniverse internals.

Step 1 — force a fresh install:

uv cache clean tooluniverse
uvx tooluniverse --version   # should pull the latest

Step 2 — check what version is running:

uvx tooluniverse --version

Step 3 — pin to latest stable if auto-update pulls a broken release:

# In your MCP config args:
"args": ["tooluniverse==<last-known-good-version>"]
# Check releases: https://github.com/mims-harvard/ToolUniverse/releases

Still Stuck? File a GitHub Issue

If none of the above fixes it, open a GitHub issue. Run this script first — it collects system info with no personal data (paths and usernames are stripped):

python3 - << 'EOF'
import sys, platform, subprocess, os, re, urllib.parse

home = os.path.expanduser("~")
def run(cmd):
    try:
        out = subprocess.check_output(cmd, shell=True, stderr=subprocess.STDOUT, text=True).strip()
    except Exception as e:
        out = f"error: {e}"
    return re.sub(re.escape(home), "~", out)

lines = [
    "**Environment**",
    f"- OS: {platform.system()} {platform.release()} {platform.machine()}",
    f"- Python: {sys.version.split()[0]}",
    f"- uv: {run('uv --version')}",
    f"- uvx: {run('uvx --version')}",
    f"- ToolUniverse: {run('uvx tooluniverse --version 2>/dev/null || echo unknown')}",
    "",
    "**Steps to reproduce**",
    "1. <describe what you did>",
    "",
    "**Error message**",
    "```",
    "<paste full error here>",
    "```",
    "",
    "**Expected behavior**",
    "<what you expected to happen>",
]

body = "\n".join(lines)
title = "Bug: <brief description>"
url = ("https://github.com/mims-harvard/ToolUniverse/issues/new"
       "?title=" + urllib.parse.quote(title)
       + "&body=" + urllib.parse.quote(body))

print("=" * 60)
print("ISSUE BODY (copy-paste if opening manually):")
print("=" * 60)
print(body)
print()
print("=" * 60)
print("PRE-FILLED ISSUE URL (open in browser):")
print("=" * 60)
print(url)
EOF

The script prints two things: 1. Issue body — copy-paste it into https://github.com/mims-harvard/ToolUniverse/issues/new 2. Pre-filled URL — open it in a browser to get a GitHub issue form with the info already filled in

If GitHub CLI (`gh`) is installed, you can create the issue directly — paste the body from above, then run:

gh issue create --repo mims-harvard/ToolUniverse \
  --title "Bug: <brief description>" \
  --body "<paste issue body here>"

You can also email Shanghua Gao with the issue body.