English Français العربية

Semantic Cache MCP

Official registry Developer tools

File cache for coding agents: re-reads cost ~40 tokens, changed files return diffs.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package semantic-cache-mcp
Claude Code 
claude mcp add semantic-cache-mcp -- uvx semantic-cache-mcp==0.7.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "semantic-cache-mcp": {
            "command": "uvx",
            "args": [
                "semantic-cache-mcp==0.7.0"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Semantic Cache MCP
  2. Quick start
  3. How it works
  4. Tools
  5. FAQ
  6. Documentation
  7. Contributing
  8. License

Semantic Cache MCP

Stop paying for the same file twice.

An MCP file cache for AI coding agents: a re-read costs ~40 tokens instead of the whole file.

Coding agents read the same files over and over: before an edit, after an edit, after every context compaction. A built-in Read sends the whole file each time. Semantic Cache MCP knows what your agent already holds. Measured on one 7,891-token file:

ReadBuilt-in ReadSemantic Cache MCP
First read7,891 tokensfull file, plus a hash
Re-read, file unchanged7,891 tokens77 tokens
Re-read after a one-line edit7,891 tokens137 tokens (a diff)

Across a 48-file project it saves 98.7% of re-read tokens, and an unchanged read takes 0.17 ms. It also gives your agent grep, BM25 search and glob over the cache, atomic edits with dry_run, and token-budgeted batch reads. Three runtime dependencies, no API keys, no GPU.

Quick start

You need uv. In Claude Code:

claude mcp add semantic-cache --scope user -- uvx semantic-cache-mcp

Any other client (Cursor, Claude Desktop, and others that take mcpServers JSON):

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

Configs for VS Code, Codex and OpenCode, and how to turn off the built-in file tools so the agent uses the cache: docs/clients.md.

How it works

Every file the server sends comes with a content_hash. The agent passes it back as known_hash on the next read:

flowchart LR
    R["read(path, known_hash)"] --> M{"hash matches<br/>the file now?"}
    M -- yes --> U["unchanged<br/>~40 tokens"]
    M -- "no, older version" --> D["diff of changed lines"]
    M -- "no hash" --> F["full file + content_hash"]
  • No stale content. Every read checks the file on disk first. unchanged only answers when the hash matches the current bytes.
  • Forgetting is safe. After a compaction, the agent reads without the hash and gets the full file back.
  • Large files become maps. A file over max_size returns an outline of its definitions, not a blind cut.
  • Everything stays local. The cache is a SQLite file. One background daemon serves every client on your machine.

Tools

read · batch_read · read_image · write · edit · batch_edit · edit_preview · delete · warm · grep · search · glob · stats · clear

Parameters and examples: docs/tools.md.

FAQ

Is the search "semantic" in the embeddings sense? No. search is BM25 keyword ranking and grep is exact. No model to download, no GPU, no API key.

Does it send my code anywhere? No. The only network request is a one-time download of the o200k tokenizer file, checked against a SHA-256 hash.

Does it work on Windows? Yes. CI runs on Linux and macOS.

Documentation

GuideCovers
ClientsSetup for each client, turning off built-in file tools
ToolsEvery tool, with parameters and examples
Environment VariablesEvery setting, with defaults
PerformanceBenchmarks and methodology
ArchitectureStorage, algorithms, the shared daemon
SecurityThreat model, size limits, path handling
TroubleshootingCommon issues, debug logging
Advanced UsagePython API

Contributing

git clone https://github.com/CoderDayton/semantic-cache-mcp.git
cd semantic-cache-mcp
uv sync --extra dev
uv run pytest

See CONTRIBUTING.md. Issues and pull requests are welcome.

License

MIT.

Frequently asked questions

What is Semantic Cache MCP?

File cache for coding agents: re-reads cost ~40 tokens, changed files return diffs.

How do I install Semantic Cache MCP?

It runs on your machine. In Claude Code: claude mcp add semantic-cache-mcp -- uvx semantic-cache-mcp==0.7.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Semantic Cache MCP need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is Semantic Cache MCP open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Semantic Cache MCP?

It is published by CoderDayton. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.