# context-doctor

> context-doctor is an open-source MCP server for ai models and llm tooling. Measure and cut wasted LLM tokens in Claude Code, Cursor, Codex and Gemini CLI. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Linux, Windows, self-hosted
- **Repository:** https://github.com/kushalp1/context-doctor
- **MCP Registry name:** io.github.KushalP1/context-doctor
- **Categories:** [AI models and LLM tooling](https://ai-powered.com/categories/ai-and-llm), [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

Long agent sessions re-send their whole context on every message, and that cost returns at full price once the prompt cache expires. context-doctor replays your own session history, request by request, and prices the waste in dollars, then shows what each fix would have saved before you apply anything.

The measuring side covers spend across Claude Code, Codex, Gemini CLI and Cursor, per-request overhead from system prompts, MCP servers and memory files, cache misses, and plan limit pace. The saving side includes a pack tool that returns only the chunks of a large document or log that a question needs, a recall tool that pulls lines from the session's own transcript, and hooks that warn about model-switch and subagent costs or guide compaction.

It runs locally with no API key and, according to the README, sends no telemetry. Besides the MCP server it ships a CLI, a Claude Code plugin, a proxy for Anthropic, OpenAI and Gemini API apps, a GitHub Action that flags growth of CLAUDE.md and rules files, and a Python helper for RAG pipelines. It is MIT licensed and needs Node 20 or newer.

## Features

- **Dollar-priced savings:** Replays recent Claude Code sessions to show what each fix would have saved.
- **Cross-tool spend:** One bill across Claude Code, Codex, Gemini CLI and Cursor by project, model and day.
- **Pack and recall:** Return only the relevant chunks of a document or of the session transcript.
- **Compaction and cost hooks:** Warn before model switches and subagent launches, and guide what compaction keeps.
- **API proxy:** Point Anthropic, OpenAI or Gemini base URLs at a local proxy to trim requests.
- **CI check:** A GitHub Action comments on how much a pull request grows CLAUDE.md and rules.

## Good for

- Find out why a long Claude Code session costs so much
- Shrink a heavy CLAUDE.md or memory file into a lean one plus a reference file
- Keep large logs or PDFs out of context while still answering questions about them
- Gate pull requests that bloat agent instruction files
- Track combined agent spend across several coding tools

## Install

### Claude Code (Terminal)

```sh
claude mcp add context-doctor -- npx -y context-doctor
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "context-doctor": {
      "command": "npx",
      "args": [
        "-y",
        "context-doctor"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "context-doctor": {
      "command": "npx",
      "args": [
        "-y",
        "context-doctor"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "context-doctor": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "context-doctor"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "context-doctor": {
      "command": "npx",
      "args": [
        "-y",
        "context-doctor"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "context-doctor": {
      "command": "npx",
      "args": [
        "-y",
        "context-doctor"
      ]
    }
  }
}
```

## Tools

- `pack_context`: Returns only the chunks of a document, log or codebase that a question needs, within a token budget.
- `recall`: Returns the lines of the current session's transcript that a question needs.

## FAQ

### Does it need an API key?

No. It runs on your machine and needs no API key.

### Does it send telemetry?

The README says it sends none.

### How do I try it without installing?

Run npx context-doctor in a terminal; it reads your last 30 days of Claude Code sessions and shows potential savings, applying changes only after you confirm.

### Can fixes be undone?

Yes. npx context-doctor fix undo puts them back.

### What does it require?

Node 20 or newer, on macOS, Linux or Windows.

### Is context-doctor free?

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

### How do I add context-doctor to Claude Code?

Run this command in your terminal: claude mcp add context-doctor -- npx -y context-doctor

### What are the best alternatives to context-doctor?

The closest alternatives to context-doctor are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

## Where this comes from

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

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/context-doctor
