Skip to main content
Glama
Sign In
token-optimization-mcp

token-optimization-mcp

by DCx7C5
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

token-optimization-mcp v0.2.0

Production-ready Model Context Protocol server for token counting, prompt compression, model routing and semantic caching. Zero external API calls — works fully offline.

Tools

Tool

Description

estimate_tokens

Count tokens for any text+model (calibrated chars/token ratios)

compress_prompt

Shrink prompts with trim, summarize_hint or aggressive strategy

route_model

Pick cheapest model meeting quality + context requirements

cache_lookup

Semantic cache hit/miss by prompt or pre-computed key

cache_store

Store prompt+result with token-savings metadata

cache_invalidate

Remove one or all cache entries

analyze_context

Conversation health: role breakdown, issues, recommendations

savings_report

Session-level token/USD savings dashboard

deduplicate_messages

Remove duplicate turns, count saved tokens

Related MCP server: TokenSaver MCP

Quick Start

cd mcps/token-optimization-mcp
uv sync

# stdio – Claude Code / Copilot
uv run main.py

# SSE – LangGraph / CrewAI / browser
uv run main.py --sse --port 8001

Environment Variables

Variable

Default

Description

USE_REDIS

false

Enable Redis backend

REDIS_URL

redis://localhost:6379/1

Redis connection URL

CACHE_TTL_SECONDS

86400

Default cache TTL (1 day)

RATE_LIMIT_PER_MIN

120

Requests/min per client

AUDIT_LOG_ENABLED

true

Print audit log to stdout

Registration

Claude Code (~/.claude/settings.json)

{
  "mcpServers": {
    "token-optimization": {
      "command": "uv",
      "args": ["run", "/path/to/token-optimization-mcp/main.py"]
    }
  }
}

VS Code Copilot (.vscode/mcp.json)

{
  "servers": {
    "token-optimization": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "${workspaceFolder}/mcps/token-optimization-mcp/main.py"]
    }
  }
}

SSE (LangGraph / CrewAI / Cursor)

http://127.0.0.1:8001/sse

Supported Models (routing catalogue)

Model

Context

Quality

Cost/1k

github:copilot

128k

8

free

gpt-4o-mini

128k

7

$0.00015

claude-3-5-haiku

200k

7

$0.00025

gemini-1.5-flash

1M

6

$0.000075

gpt-4o

128k

9

$0.005

claude-3-5-sonnet

200k

9

$0.003

claude-3-opus

200k

10

$0.015

Testing

uv run --group test pytest
# 118 tests, 100% coverage

Architecture

token-optimization-mcp/
├── main.py                      ← FastMCP server (9 tools)
├── pyproject.toml
├── README.md
├── tests/
│   ├── conftest.py              ← state-reset fixtures
│   ├── test_helpers.py          ← unit tests + Hypothesis
│   └── test_tools.py            ← integration tests per tool
└── mcp-servers/
    └── context-cache-server/    ← standalone Redis-backed sub-server
        ├── server.py
        ├── config.py
        └── security.py

Available Tools

9 tools
analyze_contextA

Analyze a list of chat messages ({role, content}) for token usage and issues. Detects bloated system prompts, near-full context windows, and repeated content. Returns per-role breakdown, issues list, and recommendations.

Inputs: messages (required), model. Returns: object

cache_invalidateA

Invalidate one or all cache entries. Pass cache_key to remove one entry, or flush_all=true to wipe everything.

Inputs: cache_key, flush_all. Returns: object

cache_lookupA

Look up a cached result by prompt text or pre-computed cache key. Returns {hit: true, result, tokens_saved} or {hit: false}.

Inputs: prompt, cache_key, client_id. Returns: object

cache_storeA

Store a prompt+result in the cache. Provide prompt (auto-hashed), result text, tokens_saved estimate, optional TTL override and metadata dict.

Inputs: prompt (required), result (required), tokens_saved (required), metadata, +2 more. Returns: object

compress_promptB

Compress a prompt to reduce token usage. strategy: 'trim' (whitespace/blanks), 'summarize_hint' (mark long sections), 'aggressive' (strip comments, examples, filler). Returns compressed text + savings stats.

Inputs: prompt (required), model, strategy, target_tokens. Returns: object

deduplicate_messagesB

Remove duplicate messages from a conversation (keeps last occurrence). Returns deduplicated list + tokens saved.

Inputs: messages (required), model. Returns: object

estimate_tokensA

Estimate token count for a text string. Uses calibrated chars/token ratios per model. Example: estimate_tokens(text='Hello world', model='gpt-4o') → {tokens: 2, ...}

Inputs: text (required), model. Returns: object

route_modelA

Recommend the cheapest capable model for a task. Filter by min_quality (1-10, default 7) and max_cost_per_1k USD. Returns ranked candidates with per-call cost estimate.

Inputs: estimated_tokens (required), min_quality, prefer_free, max_cost_per_1k, +1 more. Returns: object

savings_reportB

Token savings dashboard for the current session. Shows cache hits, tokens saved, and estimated USD savings per client.

Inputs: model. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct operation: caching (store/lookup/invalidate), compression, deduplication, analysis, estimation, model routing, and reporting. No two tools overlap in purpose.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., cache_store, compress_prompt, route_model), making them predictable and easy to differentiate.

    Tool Count5/5

    With 9 tools, the server covers the core aspects of token optimization without being excessive. Each tool serves a clear need within the domain.

    Completeness4/5

    The tool set covers analysis, caching, compression, deduplication, estimation, routing, and reporting. The only minor gap is the lack of a cache listing tool, but the core workflow is complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers