From mims-harvard-tooluniverse
Guides step-by-step ToolUniverse installation via uv for MCP chat servers (12+ AI clients like Cursor, VS Code), CLI (9 subcommands: list/grep/run/etc.), or Python SDK. Use for setup, config, CLI usage, troubleshooting.
npx claudepluginhub joshuarweaver/cascade-data-analytics --plugin mims-harvard-tooluniverseThis skill uses the workspace's default tool permissions.
Guide the user step-by-step through setting up ToolUniverse.
API_KEYS_REFERENCE.mdCLAUDE_DESKTOP.mdEXAMPLES.mdGITHUB_ISSUE.mdINSTALL.mdMCP_CONFIG.mdSKILLS_CATALOG.mdSKILL_SUMMARY.mdTRAE.mdTROUBLESHOOTING.mdreferences/mcp-configs.mdscripts/check_prerequisites.pyscripts/diagnose_setup.pyscripts/list_tool_categories.pyscripts/test_mcp_connection.pyscripts/verify_installation.pyConducts multi-round deep research on GitHub repos via API and web searches, generating markdown reports with executive summaries, timelines, metrics, and Mermaid diagrams.
Dynamically discovers and combines enabled skills into cohesive, unexpected delightful experiences like interactive HTML or themed artifacts. Activates on 'surprise me', inspiration, or boredom cues.
Generates images from structured JSON prompts via Python script execution. Supports reference images and aspect ratios for characters, scenes, products, visuals.
Guide the user step-by-step through setting up ToolUniverse.
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.
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.
Present using AskQuestion:
| Mode | What it means | Who it's for |
|---|---|---|
| Chat mode | Ask questions to an AI assistant. No coding. | Most researchers. |
| Command line | Type short commands in Terminal. | Quick tests. Terminal-comfortable users. |
| Python code | Write scripts for automated pipelines. | Programmers. |
Options: "I want to ask questions" → Chat mode | "Quick try" → CLI | "I write Python" → SDK | "I don't know" → Recommend Chat mode
If Chat mode, ask which app (AskQuestion): Cursor, Claude Desktop, VS Code/Copilot, Windsurf, Claude Code, Gemini CLI, Codex, Cline/Trae/Antigravity/OpenCode. "I don't have any" → Recommend Claude Desktop.
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
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.
| Command | What it does | Example |
|---|---|---|
tu status | Show tool count and top categories | tu status |
tu list | List tools (modes: names, categories, basic, by_category, summary, custom) | tu list --mode basic --limit 20 |
tu find | Search by natural language (keyword scoring, no API key needed) | tu find 'protein structure analysis' |
tu grep | Text/regex pattern search | tu grep '^UniProt' --mode regex |
tu info | Show tool parameters and schema | tu info PubMed_search_articles |
tu run | Execute a tool | tu run PubMed_search_articles '{"query": "CRISPR"}' |
tu test | Test a tool with its example inputs | tu test UniProt_get_entry_by_accession |
tu build | Generate typed Python wrappers for Coding API | tu build --output ./my_tools |
tu serve | Start MCP stdio server (same as uvx tooluniverse) | tu serve |
Output flags (most commands except build/serve): --json (pretty) or --raw (compact, pipe-friendly).
Continue to Step 3 (API Keys).
Make sure Step 2 is done. For detailed patterns, invoke the tooluniverse-sdk skill.
uv pip install tooluniverse
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).
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).
Make sure Step 2 is done (uv --version works).
Config file help (if user seems unfamiliar): Config files are plain text that store settings — like a preference list for the app. You don't need to understand the format; just paste exactly what's shown below. Most apps have a Settings button that opens the file for you (see table). If the file is empty, paste the entire block. If it already has content, the agent should help merge it.
Default config (same for most clients):
{
"mcpServers": {
"tooluniverse": {
"command": "uvx",
"args": ["tooluniverse"],
"env": { "PYTHONIOENCODING": "utf-8" }
}
}
}
Config file locations:
| Client | File | How to Access |
|---|---|---|
| Cursor | ~/.cursor/mcp.json | Settings → MCP → Add new global MCP server |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | Settings → Developer → Edit Config |
| Claude Code | ~/.claude.json or .mcp.json | claude mcp add or edit directly |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | MCP hammer icon → Configure |
| Cline | cline_mcp_settings.json | Cline panel → MCP Servers → Configure |
| Gemini CLI | ~/.gemini/settings.json | gemini mcp add or edit directly |
| Trae | .trae/mcp.json | Ctrl+U → AI Management → MCP → Configure |
Different formats: VS Code uses "servers" key with "type": "stdio". Codex uses TOML. OpenCode uses "mcp" key. See references/mcp-configs.md for these.
Continue to Step 3 (API Keys).
Many tools work without keys, but some unlock powerful features. Ask research interests first (AskQuestion):
Map to recommended keys (2-4 to start). Walk through one at a time: explain what it unlocks, give registration link, wait for key, add to config.
Tier 1 (Core — recommend for most users):
| Key | Unlocks | Free? | Registration |
|---|---|---|---|
NCBI_API_KEY | PubMed (rate limit 3→10/s) | Yes | https://account.ncbi.nlm.nih.gov/settings/ |
NVIDIA_API_KEY | 16 tools: AlphaFold2, docking, genomics | Yes | https://build.nvidia.com |
BIOGRID_API_KEY | Protein interaction queries | Yes | https://webservice.thebiogrid.org/ |
FDA_API_KEY | FDA adverse events, drug labels (rate 240→1000/min) | Yes | https://open.fda.gov/apis/authentication/ |
Tier 2 (Specialized — based on interests):
| Key | Unlocks | Registration |
|---|---|---|
DISGENET_API_KEY | Gene-disease associations | https://disgenet.com/academic-apply |
OMIM_API_KEY | Mendelian/rare disease | https://omim.org/api |
ONCOKB_API_TOKEN | Precision oncology | https://www.oncokb.org/apiAccess |
UMLS_API_KEY | Medical terminology | https://uts.nlm.nih.gov/uts/ |
See API_KEYS_REFERENCE.md 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).
Don't just tell — do it WITH the user.
Chat mode: Ask user to restart app. Then run a test call yourself:
list_tools or grep_tools with "PubMed" — confirm tools visibleexecute_tool("PubMed_search_articles", {"query": "CRISPR", "max_results": 1}) — confirm it worksCLI: 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.
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:
| Client | Command |
|---|---|
| Cursor | mkdir -p .cursor/skills && cp -r /tmp/tu-skills/skills/* .cursor/skills/ |
| Claude Code | mkdir -p .claude/skills && cp -r /tmp/tu-skills/skills/* .claude/skills/ |
| Windsurf | mkdir -p .windsurf/skills && cp -r /tmp/tu-skills/skills/* .windsurf/skills/ |
| Codex | mkdir -p .agents/skills && cp -r /tmp/tu-skills/skills/* .agents/skills/ |
| Gemini CLI | mkdir -p .gemini/skills && cp -r /tmp/tu-skills/skills/* .gemini/skills/ |
Clean up: rm -rf /tmp/tu-skills
Skills activate automatically based on user's question. Try: "Research the drug metformin" or "What does the literature say about CRISPR in cancer?"
CLI users: Skills are designed for AI chat agents. Use tu find, tu info, tu run instead. For full multi-step workflows, use Chat mode or build SDK pipelines.
Don't list suggestions — run a live demo WITH the user.
| Interest | First query | Skill |
|---|---|---|
| Literature | "What does the literature say about CRISPR in cancer?" | literature-deep-research |
| Drug discovery | "Research the drug metformin" | drug-research |
| Protein structure | "Find protein structures for human EGFR" | protein-structure-retrieval |
| Genomics | "What genes are associated with type 2 diabetes?" | disease-research |
| Rare diseases | "Patient with progressive ataxia and oculomotor apraxia — differential diagnosis?" | rare-disease-diagnosis |
| Drug safety | "What are the adverse events for pembrolizumab?" | pharmacovigilance |
| General | "Research the drug aspirin" | drug-research |
Run the demo — invoke the skill and show real results.
Chat mode users:
- "Research the drug [name]" — full drug profile
- "Research [disease]" — comprehensive disease analysis
- "What are the known targets of [drug]?" — target intelligence
- "What does the literature say about [topic]?" — deep literature review
- "Find protein structures for [protein]" — 3D structures
- "Is [variant] pathogenic?" — variant interpretation
- "What drugs could be repurposed for [disease]?" — repurposing
- "What are the adverse events for [drug]?" — safety analysis
- "Find clinical trials for [disease/drug]" — trial matching
- "What are the protein interactions for [gene]?" — interaction network
- "What are the clinical guidelines for [condition]?" — practice guidelines
- "Check drug interactions between [drug1] and [drug2]" — DDI analysis
Just ask naturally — I'll figure out which databases to search.
CLI users:
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"}'
After setup, write a reminder to the agent's memory file so future sessions know ToolUniverse is available.
| Client | File |
|---|---|
| Cursor | .cursor/rules/tooluniverse.md |
| Claude Code | CLAUDE.md or .claude/CLAUDE.md (append) |
| Windsurf | .windsurf/rules/tooluniverse.md |
| VS Code/Copilot | .github/copilot-instructions.md (append) |
| Codex / OpenCode | AGENTS.md (append) |
| Gemini CLI | GEMINI.md (append) |
| Cline | .clinerules/tooluniverse.md |
| Trae | .trae/rules/tooluniverse.md |
Content:
# 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.
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/mcp.json in project root.mcp.json in project root.vscode/mcp.json in project rootProject-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.
| Issue | Fix |
|---|---|
requires-python >= 3.10 | uv python install 3.12 |
uvx: command not found | Run install script from Step 2, restart terminal |
| Context window overflow | Verify using uvx tooluniverse (compact mode is default) |
ModuleNotFoundError | uv pip install tooluniverse[all] |
| MCP server won't start | Test: uvx tooluniverse in terminal. Check JSON syntax. |
| API key 401/403 | Check key in env block, restart app, verify key name |
| Upgrade needed | uv cache clean tooluniverse then restart app |
Still stuck? GitHub issues or email Shanghua Gao.
uvx tooluniverse — auto-installs, compact modeuv cache clean tooluniverse + restart