mcp-context-manager

Keep your AI agents focused and cheap.

Long chats make agents forget important things and burn tokens on old messages. This MCP server gives any agent simple tools to manage, score, compress and prune its own context – completely free and local.

Why you need this

Context windows fill up → agents lose focus
Every extra token costs money
Most memory tools are heavy or expensive
This one is pure Python, zero API keys, ready in 30 seconds

Quick Start

pip install -e .
python -m src.server

Add to Claude Desktop / Cursor / any MCP client:

{
  "mcpServers": {
    "context-manager": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-context-manager"
    }
  }
}

Tools

Tool	Purpose
`add_message`	Log a new message into a session
`get_context_health`	Score how healthy the context is (0-100)
`compress_context`	Keep important + recent messages, drop the rest
`estimate_token_savings`	Preview how many tokens you will save
`score_message_importance`	Re-score one message
`list_sessions`	See all tracked sessions
`clear_session`	Reset a session

Typical agent flow

Create a session_id (any string)
After every user/assistant message → add_message(...)
When tokens get high → get_context_health or estimate_token_savings
When needed → compress_context and use the summary

Project layout

src/
  server.py      # MCP tools
  models.py
  analyzer.py    # pure heuristics
  storage.py
tests/
mcpize.yaml

License

MIT

Daily AI project for Prevalid · Built by Prince Ruhul

Caelune

Caelune (星野) — Local-first retrieval for private Markdown, PDF, and Tika documents, with a Windows desktop app and read-only MCP server.｜本地优先的私人知识检索工具。

mcp-context-manager