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 onetool and bench commands globally.

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

uv tool install onetool-mcp --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. Config is preserved.

Location Preserved on Uninstall?
~/.onetool/ (global config) Yes
.onetool/ (project config) Yes
Tool environment No (removed)

To fully reset (including config):

uv tool uninstall onetool-mcp
rm -rf ~/.onetool/  # Optional: remove global config

From Source (Development)

git clone https://github.com/beycom/onetool-mcp.git
cd onetool
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):

Key Service Used By
OPENAI_API_KEY OpenRouter llm.transform, code.*
BRAVE_API_KEY Brave Search brave.* tools
CONTEXT7_API_KEY Context7 context7.* tools

Example secrets.yaml

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

Resolution order: OT_SECRETS_FILE > .onetool/config/secrets.yaml > ~/.onetool/config/secrets.yaml

Configuration Variables

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

Transform Tool Configuration

The transform tool requires explicit configuration in onetool.yaml:

tools:
  transform:
    base_url: "https://openrouter.ai/api/v1"  # Required
    model: "openai/gpt-5-mini"                 # Required

The tool is not available until both base_url and model are configured, plus OPENAI_API_KEY in secrets.

MCP Configuration

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "onetool": {
      "command": "onetool"
    }
  }
}

Project Setup

Create a .onetool/ directory in your project:

Platform Global Config Project Config
macOS/Linux ~/.onetool/ .onetool/
Windows %USERPROFILE%\.onetool\ .onetool\

External Tools

# macOS
brew install ripgrep

# Linux
apt install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

Verify Installation

# Check version
onetool --version

# Start MCP server
onetool

# Run benchmarks (from source)
OT_CWD=demo bench run demo/bench/features.yaml

Next Steps