MCP Token Optimizer
MCP server that finds and cuts Claude Code token waste from sessions and MCP servers
- Pricing
- Open source
- Platforms
- CLI, macOS, Linux
- Runs
- Locally
- Version
- 0.1.1
- Listing updated
- today
Similar MCP servers
About MCP Token Optimizer
MCP Token Optimizer is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.
The README says the server looks at local Claude Code activity to find what is driving token use, mainly context size: each message re-sends the whole conversation, so long sessions get expensive quickly. It ranks recommendations from oversized live and past contexts, file reads and MCP servers that flood the context, unused servers, and idle sessions.
Most tools are read-only reports. Actions such as stopping idle sessions or disabling MCP servers default to a dry run and only apply with an explicit flag. Stopping sends SIGTERM only to Claude Code CLI processes, and transcripts are kept so sessions can be resumed. Disabled servers are either switched off with Claude Code's own settings or moved to a parked file that can be restored, with backups written before each change.
It suits developers who run Claude Code heavily and want to see where their usage goes. The README notes that process listing relies on ps, so the session tools do nothing on Windows, and that MCP tool definition costs are not measured.
Install
Run in a terminal
claude mcp add mcp-token-optimizer -- npx -y @guardbee/mcp-token-optimizerAdd to claude_desktop_config.json
{
"mcpServers": {
"mcp-token-optimizer": {
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-token-optimizer"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"mcp-token-optimizer": {
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-token-optimizer"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"mcp-token-optimizer": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-token-optimizer"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"mcp-token-optimizer": {
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-token-optimizer"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"mcp-token-optimizer": {
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-token-optimizer"
]
}
}
}Using several servers? Build one config file with the MCP config generator.
Tools this server provides (6)
Taken from the project documentation; the running server may differ.
- optimize_report
- Ranked recommendations on oversized contexts, file reads, unused MCP servers, idle sessions, and subagent and model mix.
- list_sessions
- Lists running Claude Code processes with uptime, CPU, busy or idle state, context size and recent spend.
- stop_sessions
- Stops sessions by pid or idleHours; dry run by default.
- audit_mcp_servers
- Lists every MCP server Claude Code loads with calls and output volume.
- disable_mcp_servers
- Turns servers off for new sessions without losing config; dry run by default.
- restore_mcp_servers
- Undoes disable_mcp_servers; dry run by default.
What it does
- Ranked optimization report
- Lists prioritized recommendations covering oversized contexts, chatty file reads, unused MCP servers and idle sessions.
- Session listing
- Shows running Claude Code processes with uptime, CPU, busy or idle state, context size and recent spend.
- MCP server audit
- Lists every MCP server Claude Code loads, with call counts and output volume.
- Dry-run by default actions
- Stopping sessions and toggling MCP servers preview changes unless --apply is passed.
- Reversible server disabling
- Parks disabled servers for later restore and backs up original config files before every write.
Good for
- Finding which long sessions are driving most of a Claude Code token bill
- Disabling MCP servers that have not been used in the last week
- Stopping idle Claude Code sessions left running in the background
- Checking how much output a given MCP server adds to the context
Pricing
Open source
Free npm package; source repository has an OSI license per README badge.
MCP Token Optimizer FAQ
Does it send my data anywhere?
The README says it reads local files and changes only what you tell it to. Telemetry is off by default and is handled by a separate package.
Does it work on Windows?
No for the session tools. The README says list_sessions and stop_sessions do nothing on Windows because process listing uses ps.
Can I undo a disabled MCP server?
Yes. restore_mcp_servers reverses disable_mcp_servers, and with no arguments it lists what is currently parked.
Is MCP Token Optimizer free?
Yes. MCP Token Optimizer is open source, so you can use and self-host it for free.
How do I add MCP Token Optimizer to Claude Code?
Run this command in your terminal: claude mcp add mcp-token-optimizer -- npx -y @guardbee/mcp-token-optimizer
What are the best alternatives to MCP Token Optimizer?
The closest alternatives to MCP Token Optimizer are MCP Claude Usage Guard, MCPProxy, Crimson Crab MCP Template, OneTool MCP and mcpstat.
Where this comes from
- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.