caveman-mcp

<p align="center"> <img width="200" height="200" src="https://raw.githubusercontent.com/alexruco/caveman-mcp/refs/heads/main/images/caveman-mcp.png" alt="hammer"

</p> <div class="install-box">

Install caveman-mcp

<pre><code class="bash"> pip install caveman-mcp </code></pre>

</div>

<p class="install-alt"> or run without installing: <code>uvx caveman-mcp</code> </p> <h1 align="center">caveman-mcp</h1>

<p align="center"> <strong>MCP server that cuts 65% of tokens by compressing markdown files and activating caveman speak.</strong><br/> Thinner and simpler than the original — no file distribution, no sync. No API key. Works everywhere. </p>

<p align="center"> <a href="https://pypi.org/project/caveman-mcp"><img src="https://img.shields.io/pypi/v/caveman-mcp?style=flat&color=blue" alt="PyPI"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat" alt="License"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green?style=flat" alt="MCP"></a> </p>

---

Why

Every token you send costs money and fills context. Long markdown files — CLAUDE.md, memory files, notes, docs — get read on every session. Caveman compresses them in place, preserving all code and structure, cutting prose by 65%.

Without caveman (69 tokens)	With caveman (19 tokens)
"The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I'd recommend using useMemo to memoize the object."	"New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."

Same fix. 75% fewer tokens.

Why MCP

Caveman prompts used to require a file in every project. With MCP:

• Register once — works across all projects, all agents
• No file to sync — no copy-pasting prompts into repos
• Tools included — compress any markdown file directly from the agent
• Any client — Claude Code, Cursor, Windsurf, Cline, or any MCP-compatible host

Install

pip install caveman-mcp

Or run without installing:

uvx caveman-mcp

Connect

Claude Code (global — recommended):

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "caveman-mcp": {
      "command": "uvx",
      "args": ["caveman-mcp"]
    }
  }
}

Or per-project via CLI:

claude mcp add caveman-mcp uvx -- caveman-mcp

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "caveman-mcp": {
      "command": "uvx",
      "args": ["caveman-mcp"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "caveman-mcp": {
      "command": "uvx",
      "args": ["caveman-mcp"]
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_settings.json):

{
  "mcpServers": {
    "caveman-mcp": {
      "command": "uvx",
      "args": ["caveman-mcp"]
    }
  }
}

Cline (MCP settings panel → Add Server):

{
  "command": "uvx",
  "args": ["caveman-mcp"]
}

Note: Claude Code CLI and Claude desktop app both support local (stdio) MCP servers. Claude.ai web app only supports remote (HTTP/SSE) connectors.

Without uvx (local clone):

{
  "command": "/path/to/.venv/bin/python",
  "args": ["-m", "caveman_mcp.server"]
}

Prompts

Once connected, activate caveman speak from any agent with /caveman, "talk like caveman", or "caveman mode". Stop with "stop caveman" or "normal mode".

Prompt	What it does
caveman	Activate caveman compression
caveman-commit	Terse commit message style
caveman-review	One-line code review comments
caveman-help	Quick-reference card

Intensity levels

Mode	Effect
lite	Drop filler, keep full sentences and articles
full	Default — drop articles, fragments OK, short synonyms
ultra	Abbreviate (DB/auth/req/res/fn), strip conjunctions, X→Y causality
wenyan-lite	Semi-classical Chinese register
wenyan-full	Full 文言文, 80–90% character reduction
wenyan-ultra	Extreme, ancient scholar feel

Compress Tools

Compress any markdown file in three steps — the agent does the work, caveman-mcp handles the I/O and validation.

compress_prepare(filepath)

Reads the file, returns content + compression instructions. The agent compresses the prose, then calls compress_write.

compress_prepare("CLAUDE.md")
→ { filepath, original_content, instructions }

Refuses: sensitive files (~/.ssh/, .env, credentials), existing backups, non-text formats, files > 500 KB.

compress_write(filepath, compressed_content)

Writes compressed content. Auto-creates a .original.md backup on first call. Returns { valid, errors } — validates that all headings, code blocks, and URLs are intact.

compress_restore(filepath)

Restores from .original.md backup. Call if something goes wrong.

Flow:

compress_prepare("CLAUDE.md")       ← read + get instructions
  → agent compresses prose
compress_write("CLAUDE.md", result) ← write + validate
  → { valid: true, errors: [] }

The result:

CLAUDE.md          ← compressed (65% fewer tokens every session)
CLAUDE.original.md ← full backup (edit this, re-compress anytime)

Auto-compress with Claude Code hook

Compress files automatically whenever Claude reads them — no manual invocation needed.

1. Create the hook script (~/bin/caveman-hook):

#!/usr/bin/env python3
"""PostToolUse hook: compress .md files via caveman MCP when auto mode is on."""
import json, os, sys

flag = os.path.expanduser("~/.claude/caveman-auto")
if not os.path.exists(flag):
    sys.exit(0)

data = json.load(sys.stdin)
filepath = data.get("tool_input", {}).get("file_path", "")

if not filepath.endswith(".md"):
    sys.exit(0)

backup = filepath.replace(".md", ".original.md")
if os.path.exists(backup):
    sys.exit(0)

print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "PostToolUse",
        "additionalContext": (
            f"caveman-auto is ON. Compress {filepath} now using the three-step workflow: "
            "compress_prepare → compress the prose → compress_write. "
            "Do this silently without announcing it."
        )
    }
}))

chmod +x ~/bin/caveman-hook

2. Create the toggle script (~/bin/caveman-toggle):

#!/usr/bin/env python3
import os

flag = os.path.expanduser("~/.claude/caveman-auto")
if os.path.exists(flag):
    os.remove(flag)
    print("caveman: OFF")
else:
    open(flag, "w").close()
    print("caveman: ON")

chmod +x ~/bin/caveman-toggle

3. Register the hook in ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /Users/you/bin/caveman-hook",
            "statusMessage": "caveman check..."
          }
        ]
      }
    ]
  }
}

Toggle: run python3 ~/bin/caveman-toggle to turn auto-compress on or off. To use as a bare command, add ~/bin to PATH via ~/.zprofile (not .zshrc):

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zprofile

Files with an existing .original.md backup are skipped automatically.

Attribution

Fork of JuliusBrussee/caveman — MIT licence, copyright © 2026 Julius Brussee. Original prompt design and caveman concept by Julius Brussee. This fork repackages caveman as a single MCP server with file compression tools.

License

MIT