Install and configure ToolUniverse for any use case — MCP server (chat-based), CLI (command line with 9 subcommands), or Python SDK (Coding API with 3 calling patterns). Covers uv/uvx setup, MCP configuration for 12+ AI clients (Cursor, Claude Desktop, Windsurf, VS Code, Codex, Gemini CLI, Trae, Cli

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: 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](https://claude.ai/download). 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. (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: First run takes ~30s (downloads package), then instant. Shortcut : uv tool install tooluniverse → then just use tu directly. All CLI subcommands 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 (also regenerates the internal lazy load registry in place — unaffected by output ) 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). SDK Setup Install uv first (Step 2). Do not use system pip . On a current Mac (Homebrew Python 3.13/3.14) pip install tooluniverse stops with error: externally managed environment (PEP 668), and python3 m venv can fail at ensurepip . uv avoids both because it downloads and manages its own Python. uv pip install needs an active virtualenv — run uv venv first, or use uv tool install tooluniverse if you only want the tu command. For detailed patterns, invoke the tooluniverse sdk skill. Optional extras : the base install covers API/database tools. Local ML, cheminformatics, and plotting tools need extras — uv pip install 'tooluniverse[ml]' , [visualization] , [bioinformatics] , or [all] . Run tooluniverse doctor to see which groups you are missing. Note [all] does not include singlecell , smolagents , client , or build ; install those separately. Coding API — 3 calling patterns Pattern 1: Direct import (typed, with autocomplete): Pattern 2: Attribute access (no import needed per tool): Pattern 3: JSON based (dynamic, for pipelines): 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) Offer the two low effort paths first. Editing JSON by hand is the fallback, not the recommendation — a mistyped comma is the single most common setup failure. Only walk through the manual path if neither option below fits. Path A — let an AI agent do it. If the user already has any agent (Claude, Cursor, Copilot, Gemini, Codex...), they can paste this into it: The agent handles config, keys, skills, and validation. No terminal, no JSON. Path B — Claude Code or Codex users: one liner, no config file at all. Claude Code: See the tooluniverse claude code plugin skill's "Recommended: turn on auto update" step so future releases apply without manual claude plugin update . Codex: See the tooluniverse codex plugin skill for verification, updates, and troubleshooting. Both install the MCP server plus 100+ skills in one step. Google Antigravity users: see the tooluniverse antigravity plugin skill instead — its install flow differs ( agy plugin install , not a marketplace add). Manual config (fallback) 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): Paste safely. Copy the block whole — do not retype it. If the file already has an mcpServers block, add only the "tooluniverse": { ... } entry inside it and put a comma after the previous entry. If the file was empty, paste the whole block. Then validate before restarting the app: A trailing comma after the last entry, or a missing one between entries, is the usual cause of "MCP server won't start". args — ["tooluniverse"] vs [" refresh", "tooluniverse"] : plain is the default and starts fast from uv 's cache, but can stay on a cached older release until you run uv cache clean tooluniverse . Adding refresh checks PyPI for the newest version on every launch — always current, a few seconds slower to start. Use plain unless the user specifically wants auto updates. 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 (or use plugin — see above) 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](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): 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](API KEYS REFERENCE.md) for the complete list with all tiers. Adding keys: Chat mode — add to env block in MCP config: CLI — set environment variables: 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: 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: 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. 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): Interest First query Skill Literature "What does the literature say about CRISPR i

setup-tooluniverse