# Installation

**Python 3.11+ required.**

For the quickest path, see [Quickstart](quickstart.md). 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:**

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

**Linux (Debian/Ubuntu):**

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

**Windows:**

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

## Install

```bash
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]'` |

```bash
# 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`:

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

## Upgrade

```bash
uv tool upgrade onetool-mcp
```

Or to upgrade all tools:

```bash
uv tool upgrade --all
```

## Uninstall

```bash
uv tool uninstall onetool-mcp
```

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

## From Source (Development)

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

### Local Development Install

```bash
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](https://brave.com/search/api/) | `brave.*` tools |
| `CONTEXT7_API_KEY` | [Context7](https://context7.com) | `context7.*` tools |

### Example secrets.yaml

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

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

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

Or using the CLI:

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

## External Tools

### Ripgrep Search

```bash
# macOS
brew install ripgrep

# Linux
apt install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC
```

## Verify Installation

```bash
# Check version
onetool --version

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

```

## Next Steps

- [Configuration](configuration.md) - YAML schema and options
- [CLI Reference](../reference/cli/onetool.md) - Command-line tools
