# ctxprune

> ctxprune is an open-source MCP server for developer tools. Local MCP server and CLI that shrinks logs, JSON and test output before an LLM reads them. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, API, Linux, macOS, Windows
- **Repository:** https://github.com/riceharvest/ctxprune
- **MCP Registry name:** io.github.riceharvest/ctxprune
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-19

## About

The README describes ctxprune as a local tool for reducing how many tokens an LLM reads from big logs, JSON dumps and test output. Its lossless mode rewrites tool output so it takes fewer tokens while every key and value can still be recovered, and a separate token-pruning mode deletes low-value words when a lossy result is acceptable.

As an MCP server it exposes two read tools, one lossless and one pruned, that run over stdio and read only the files a client asks for. The same functionality is available as a Python library with LangChain and LlamaIndex integrations, a command-line filter for piped output, and per-agent hooks for coding assistants such as Claude Code.

The README says nothing leaves the machine in the default preset and that the hooks use only the Python standard library. Its savings figures are measured on the author's own trace sets, and the author reports that lossy modes can change what an agent does next, so the lossless path is the default.

## Features

- **Lossless output compaction:** Rewrites large logs and JSON so the original content can be decoded back, with byte-exact checks on each rule.
- **Token pruning mode:** Deletes low-value words at a chosen keep ratio, with an option to protect identifiers, numbers and paths.
- **Two MCP read tools:** Provides read_compact and read_pruned tools to any MCP client over stdio.
- **Local-only operation:** Runs on the local machine with no API key and no network calls in the default preset.
- **RAG pipeline integrations:** Includes LangChain document compressor and LlamaIndex node postprocessor classes.
- **Command-line filter:** Pipes command output through ctxprune with a set keep ratio from the shell.

## Good for

- Reading large JSON dumps or MCP results without filling the model context
- Trimming test runner or CI output before pasting it into a chat
- Compressing retrieved documents in a LangChain or LlamaIndex pipeline
- Letting an MCP client read big log files through a compacted view

## Install

### Claude Code (Terminal)

```sh
claude mcp add ctxprune -- uvx ctxprune
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "ctxprune": {
      "command": "uvx",
      "args": [
        "ctxprune"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "ctxprune": {
      "command": "uvx",
      "args": [
        "ctxprune"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "ctxprune": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "ctxprune"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "ctxprune": {
      "command": "uvx",
      "args": [
        "ctxprune"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "ctxprune": {
      "command": "uvx",
      "args": [
        "ctxprune"
      ]
    }
  }
}
```

## Tools

- `read_compact`: Reads a file through the lossless safe pipeline, with optional start and end lines.
- `read_pruned`: Reads a file with token pruning at a chosen keep ratio, protecting identifiers by default.

## FAQ

### Does it send data anywhere?

The README says nothing leaves the machine and the safe preset makes no network calls. The token-pruning model is downloaded from Hugging Face on first use.

### Is the lossless mode really lossless?

The README says the decoder returns the original bytes for most rules, and it lists exceptions such as ANSI colour removal and JSON whitespace compaction, which keep values but not exact bytes.

### Which license does it use?

The README states the package is licensed under 0BSD, with earlier versions under Apache-2.0.

### Is ctxprune free?

Yes. ctxprune is open source, so you can use and self-host it for free.

### How do I add ctxprune to Claude Code?

Run this command in your terminal: claude mcp add ctxprune -- uvx ctxprune

### What are the best alternatives to ctxprune?

The closest alternatives to ctxprune are MCP Token Optimizer, headroom, AsterMind MCP, OneTool MCP and Trace MCP.

## Where this comes from

- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [MCP Token Optimizer](https://ai-powered.com/mcp/mcp-token-optimizer-2): MCP Token Optimizer is an open-source MCP server for developer tools.
- [headroom](https://ai-powered.com/mcp/headroom-3): headroom is an open-source MCP server for ai models and llm tooling.
- [AsterMind MCP](https://ai-powered.com/mcp/astermind-mcp): AsterMind MCP is a free MCP server for ai models and llm tooling.
- [OneTool MCP](https://ai-powered.com/mcp/onetool-mcp): OneTool MCP is an open-source MCP server for developer tools.
- [Trace MCP](https://ai-powered.com/mcp/trace-mcp): Trace MCP is a freemium MCP server for developer tools.
- [Token Context MCP](https://ai-powered.com/mcp/token-context-mcp): Token Context MCP is an open-source MCP server for developer tools.
- [Crimson Crab MCP Template](https://ai-powered.com/mcp/crimson-crab-mcp-template): Crimson Crab MCP Template is an open-source MCP server for ai models and llm tooling.
- [Logmcp](https://ai-powered.com/mcp/logmcp): Logmcp is an open-source MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/ctxprune
