caveman-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@caveman-mcp compress my CLAUDE.md file"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Install caveman-mcp
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 |
Same fix. 75% fewer tokens.
Related MCP server: toon-parse-mcp
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-mcpOr run without installing:
uvx caveman-mcpConnect
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-mcpClaude 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 |
| Activate caveman compression |
| Terse commit message style |
| One-line code review comments |
| Quick-reference card |
Intensity levels
Mode | Effect |
| Drop filler, keep full sentences and articles |
| Default — drop articles, fragments OK, short synonyms |
| Abbreviate (DB/auth/req/res/fn), strip conjunctions, X→Y causality |
| Semi-classical Chinese register |
| Full 文言文, 80–90% character reduction |
| 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-hook2. 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-toggle3. 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"' >> ~/.zprofileFiles 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
Available Tools
3 toolscompress_prepareA
Read a file and return its content with compression instructions. No API key needed — the calling agent compresses the returned content, then passes it to compress_write.
Inputs: filepath (required). Returns: object
compress_restoreA
Restore file from its .original.md backup and delete the backup. Call this if compression validation keeps failing after retries.
Inputs: filepath (required). Returns: result
compress_writeA
Write compressed content to file. Creates backup on first call; overwrites on retry. Returns {valid, errors}. If errors persist after retries, call compress_restore.
Inputs: filepath (required), compressed_content (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a distinct role in the compression workflow: compress_prepare reads and provides compression instructions, compress_write writes compressed content with backup, and compress_restore reverts. No overlap.
All tools follow the 'compress_[verb]' pattern with clear verbs (prepare, restore, write), ensuring predictability and readability.
Three tools is minimal but well-scoped for a focused compression utility. The set covers the essential operations without unnecessary bloat.
The tools cover the key operations: read/prepare, write/compress with backup, and restore. Missing an explicit compression tool is acceptable since the server delegates compression to the agent.
Maintenance
Related MCP Connectors
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Free, no-key MCP server: token estimates, JSON Schema conversion, MCP configs, tool search.
An MCP server that gives your AI access to the source code and docs of all public github repos
MCP server for Grok Imagine AI video generation
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that helps AI agents reduce token usage by compressing, summarizing, and managing conversation/context data more efficiently.11MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that helps AI agents reduce token usage by converting data to TOON format and stripping comments and unnecessary whitespace from code files.89 PyPIMIT
- AlicenseAqualityDmaintenanceAn MCP server that reduces AI API costs by up to 97% through token measurement, compression, caching, and pruning, all without changing prompts.101Apache 2.0
- FlicenseNot gradedqualityDmaintenanceAn MCP server suite that optimizes prompt context by reducing tokens up to 98.8%, acting as persistent long-term memory and codebase scanner to save API costs.-