# token-savior

Search a codebase by symbol and carry project context across sessions. Useful when an agent needs to navigate code without repeatedly reading whole files.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 1189
- Author: Mibayy
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Mibayy/token-savior
- Updated: 2026-10-15
- HTML: https://affpapa.org/en/nevibecode/mcp/token-savior

## What it does

token-savior gives coding agents structural code search and persistent memory across sessions. It can connect to Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, and Zed. Set `WORKSPACE_ROOTS` to the project paths the server should work with.

The `optimized` profile combines a smaller tool manifest, thinner input schemas, and memory settings designed for cross-project safety. Bash rewriting and output compaction are opt-in. In Claude Code, set `alwaysLoad: true`; otherwise, the server’s tools can sit behind ToolSearch while the agent falls back to `Read` and `Grep`.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `WORKSPACE_ROOTS`, `TOKEN_SAVIOR_CLIENT`, `TOKEN_SAVIOR_PROFILE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env WORKSPACE_ROOTS=<WORKSPACE_ROOTS> --env TOKEN_SAVIOR_CLIENT=<TOKEN_SAVIOR_CLIENT> --env TOKEN_SAVIOR_PROFILE=<TOKEN_SAVIOR_PROFILE> --transport stdio token-savior -- uvx token-savior-recall
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from token-savior-recall <command>

### Codex

**Platform CLI**
```bash
codex mcp add token-savior --env WORKSPACE_ROOTS=<WORKSPACE_ROOTS> --env TOKEN_SAVIOR_CLIENT=<TOKEN_SAVIOR_CLIENT> --env TOKEN_SAVIOR_PROFILE=<TOKEN_SAVIOR_PROFILE> -- uvx token-savior-recall
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from token-savior-recall <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "token-savior": {
            "command": "uvx",
            "args": [
                "token-savior-recall"
            ],
            "env": {
                "WORKSPACE_ROOTS": "<WORKSPACE_ROOTS>",
                "TOKEN_SAVIOR_CLIENT": "<TOKEN_SAVIOR_CLIENT>",
                "TOKEN_SAVIOR_PROFILE": "<TOKEN_SAVIOR_PROFILE>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from token-savior-recall <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "token-savior": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "token-savior-recall"
            ],
            "env": {
                "WORKSPACE_ROOTS": "<WORKSPACE_ROOTS>",
                "TOKEN_SAVIOR_CLIENT": "<TOKEN_SAVIOR_CLIENT>",
                "TOKEN_SAVIOR_PROFILE": "<TOKEN_SAVIOR_PROFILE>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from token-savior-recall <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e WORKSPACE_ROOTS=<WORKSPACE_ROOTS> -e TOKEN_SAVIOR_CLIENT=<TOKEN_SAVIOR_CLIENT> -e TOKEN_SAVIOR_PROFILE=<TOKEN_SAVIOR_PROFILE> token-savior uvx token-savior-recall
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from token-savior-recall <command>

## When to use it
- find symbol definitions and references across a project
- restore project context between agent sessions
- reduce the size of the tool manifest
- rewrite Bash commands and compact their output

## Example prompts
- Find the definition and call sites for `UserService` in this project.
- Restore the saved project context before changing the code.
- Compact Bash command output and rewrite commands before execution.

## Similar
- [token-integration-analyzer](https://affpapa.org/en/nevibecode/skills/token-integration-analyzer.md) — skill · 5500 installs
- [token-efficiency](https://affpapa.org/en/nevibecode/skills/token-efficiency.md) — skill · 2500 installs
- [design-token](https://affpapa.org/en/nevibecode/skills/design-token.md) — skill · 2200 installs
- [token-optimizer](https://affpapa.org/en/nevibecode/skills/token-optimizer.md) — skill · 976 installs
- [caveman-token-optimizer](https://affpapa.org/en/nevibecode/skills/caveman-token-optimizer.md) — skill · 842 installs
- [pay-with-any-token](https://affpapa.org/en/nevibecode/skills/pay-with-any-token.md) — skill · 815 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md