# Token Optimizer MCP server

> Compresses AI coding agent context to cut token costs, measure per-agent savings, and share a local knowledge graph across 16 CLI clients.

- Repository: https://github.com/ooples/token-optimizer-mcp
- Page: https://hostedmcp.org/servers/ooples/token-optimizer-mcp
- Transport: stdio
- Stars: 581
- License: MIT
- Latest version: 7.11.0

## Install

### Claude Code

```sh
claude mcp add token-optimizer-mcp -- npx -y @ooples/token-optimizer-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "token-optimizer-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ooples/token-optimizer-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "token-optimizer-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ooples/token-optimizer-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"token-optimizer-mcp","type":"stdio","command":"npx","args":["-y","@ooples/token-optimizer-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "token-optimizer-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ooples/token-optimizer-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add token-optimizer-mcp -- npx -y @ooples/token-optimizer-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.token-optimizer-mcp]
command = "npx"
args = ["-y", "@ooples/token-optimizer-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user token-optimizer-mcp npx -- -y @ooples/token-optimizer-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "token-optimizer-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ooples/token-optimizer-mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `ORCAROUTER_API_KEY` | no | no |  |
| `TOKEN_OPTIMIZER_CACHE_DIR` | no | no | Directory path for cache storage (optional, defaults to ~/.token-optimizer-cache) |
| `TOKEN_OPTIMIZER_LARGE_READ_BYTES` | no | no |  |
| `TOKEN_OPTIMIZER_MODE` | no | no |  |
| `TOKEN_OPTIMIZER_ORCA_MODEL` | no | no |  |
| `TOKEN_OPTIMIZER_ROLLOUT_CHANNEL` | no | no |  |

## Tools (10)

- `wiki_write`: Record a durable finding in this project's knowledge graph so a later session retrieves it instead of re-deriving it. Use it the moment you conclude something that cost real work and is not obvious from the code: a dead end and why, a decision and its rejected alternatives, a command that finally worked, or how a subsystem fits together. Anchor it to the files it is about — the anchor is what lets the claim be invalidated when that code changes, and what makes it surface automatically when the file is next touched. Costs nothing and sends nothing off the machine.
- `wiki_query`: Read the project's knowledge graph: fetch a finding by key, search findings by terms, inspect a node and its neighbours, or get the graph's audit, token balance and overall shape. Use it when the session index mentions a finding you want in full, or to find out what the graph holds at all. NOT for anchored retrieval: to ask what is known about a particular file or symbol, call wiki_read, which does exactly that and is the tool the enforcement layer points at. (read-only)
- `expand`: Retrieve the full output behind a preview reference, served from the local store rather than by re-running anything. Pass `section` to say which named part of the preview you needed -- that is what teaches the next preview to keep it. Pass `claim` and `anchor` to record what you learned, so the same expansion never happens again.
- `optimize_session`: Analyzes operations in the current session from the session JSONL log, identifies large text blocks from file-based tools (Read, Write, Edit), compresses them, and stores them in the cache to reduce future token usage. Returns a summary of the optimization.
- `smart_read`: Read files with intelligent caching, diff-based updates, and syntax-aware optimization. Measured token reduction vs reading the file: -2% to 0% first read, 99-99.9% repeated on an unchanged file (bench/tools, 3 fixtures) -- a first read returns the file plus a one-field header, so it still costs a little more than reading the file; the saving is on the repeat. (read-only)
- `smart_write`: Write files with an unmeasured design target of 85% token reduction through verification, atomic operations, and change tracking
- `smart_edit`: Edit files with an unmeasured design target of 90% token reduction through line-based operations and diff-only output
- `smart_glob`: Search files with glob patterns and an unmeasured design target of 75% token reduction through path-only results and smart filtering (read-only)
- `smart_grep`: Search file contents with an unmeasured design target of 80% token reduction through match-only output and smart filtering (read-only)
- `get_optimization_report`: Get a provenance-gated token report. Verified savings require a materialized MCP payload before and after optimization; historical and tool-reported estimates are excluded. Direct API-price equivalents use each exact captured model and route; ambiguous operations remain unpriced.

## FAQ

### How much does Token Optimizer reduce token usage?

Over its benchmark corpus the proxy removes 82.5% of characters and 91.5% of tokens, while the block engine alone removes 72.0% and 55.9%.

### Does Token Optimizer send telemetry?

No, telemetry is opt-in and off by default.

### What license does Token Optimizer use?

It is MIT licensed and commercial use is allowed.

### What Node.js version does Token Optimizer require?

It requires Node.js 22.14 or newer.
