Skip to content

Installation

Python 3.11+ required.

For the quickest path, see Quickstart. This page covers all platforms and optional features.

System Requirements

Requirement Version Purpose
Python >= 3.11 Runtime environment
uv Latest Package management

Installing System Requirements

macOS:

brew install python@3.11
curl -LsSf https://astral.sh/uv/install.sh | sh

Linux (Debian/Ubuntu):

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

Windows:

winget install Python.Python.3.11
irm https://astral.sh/uv/install.ps1 | iex

Install

uv tool install onetool-mcp

This installs the onetool command globally with the core tool set.

Optional Tool Packs

Tools are split into optional extras for leaner installs:

Extra Tools Install
[util] brave, convert, excel, file, ground, knowledge, mem, tavily uv tool install 'onetool-mcp[util]'
[dev] aws, chrome_util, context7, db, diagram, package, play_util, ripgrep, webfetch, whiteboard uv tool install 'onetool-mcp[dev]'
[all] Everything uv tool install 'onetool-mcp[all]' 
# Install with all tools
uv tool install 'onetool-mcp[all]'

# Install with specific extras
uv tool install 'onetool-mcp[util,dev]'

Optional: For safe file deletion (moves to trash instead of permanent delete), add send2trash:

uv tool install 'onetool-mcp[all]' --with send2trash

Upgrade

uv tool upgrade onetool-mcp

Or to upgrade all tools:

uv tool upgrade --all

Uninstall

uv tool uninstall onetool-mcp

This removes the tool and its isolated environment. Any config directories you created are preserved.

From Source (Development)

git clone https://github.com/beycom/onetool-mcp.git
cd onetool-mcp
uv sync --group dev

Local Development Install

uv tool install -e .

Code changes are picked up immediately. Reinstall only for new entry points, dependencies, or top-level packages.

API Keys

API keys are stored in secrets.yaml (gitignored) and passed to the server via --secrets:

Key Service Used By
OPENAI_API_KEY OpenAI-compatible providers (including OpenRouter) ot_llm.transform
BRAVE_API_KEY Brave Search brave.* tools
CONTEXT7_API_KEY Context7 context7.* tools

Example secrets.yaml

# secrets.yaml
BRAVE_API_KEY: "BSA..."
OPENAI_API_KEY: "sk-..."
CONTEXT7_API_KEY: "c7-..."

Pass it to the server via --secrets /path/to/secrets.yaml. If omitted, no secrets are loaded.

Configuration Variables

Variable Default Purpose
OT_LOG_LEVEL INFO Logging verbosity
OT_LOG_DIR ../logs Log file directory (relative to config)

LLM Configuration

Configure base_url and model once at the top level — all LLM-using tools (ot_llm, ot_image, mem, knowledge, ctx) inherit from it:

llm:
  base_url: "https://openrouter.ai/api/v1"    # Required
  model: "google/gemini-2-flash-preview"       # Required for transform/vision
  embedding_model: "text-embedding-3-small"    # Required for mem/knowledge embeddings

The transform tool is not available until base_url and model are configured (via llm: or tools.ot_llm.*), plus OPENAI_API_KEY in secrets.

MCP Configuration

Claude Code

Add to ~/.claude/mcp.json (or use claude mcp add):

{
  "mcpServers": {
    "onetool": {
      "command": "onetool",
      "args": ["--config", "/path/to/.onetool/onetool.yaml", "--secrets", "/path/to/.onetool/secrets.yaml"]
    }
  }
}

Or using the CLI:

claude mcp add onetool -- onetool --config ~/.onetool/onetool.yaml --secrets ~/.onetool/secrets.yaml

External Tools

# macOS
brew install ripgrep

# Linux
apt install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

Verify Installation

# Check version
onetool --version

# Initialize and validate config
onetool init --config ~/.onetool
onetool init validate --config ~/.onetool/onetool.yaml

Next Steps