stash-mcp

Stash-MCP

A file-backed content server that exposes documents to AI agents via the Model Context Protocol.
Files on disk are the source of truth — agents read them as MCP resources and update them through MCP tools.

Quick Start • Features • The UI • Usage • Configuration • Full Docs

---

Features

• Centralized knowledge store — One place to stash documentation, notes, specs, and reference material that any connected agent can access
• File-first design — Files on disk are the source of truth. No database layer. Inspect, edit, or manage content directly on the filesystem
• MCP native — Content is exposed as MCP resources (read path) and MCP tools (write path), so agents can both consume and update documentation
• Rich rendering — Markdown with Mermaid diagrams, syntax-highlighted code, and a built-in OpenAPI viewer for .json specs
• Semantic search (opt-in) — Vector-based search across all stashed content, with pluggable embedding providers
• Git tracking (opt-in) — File history, diffs, and blame are exposed as MCP tools; writes are gated behind atomic git-committed transactions
• Read-only mode — Serve reference docs to agents without allowing any modifications
• Simple deployment — Single Docker container with a volume mount. No external dependencies

The UI

Stash-MCP ships with a browser UI so humans can curate the same content their agents are reading. It uses the same filesystem as the MCP server — anything an agent writes shows up immediately, and anything you write is available to the agent on the next read.

Browse the content tree with rendered Markdown	Tables, callouts, and headings, with an on-page outline
OpenAPI .json specs render as a grouped endpoint list	Edit content in-browser with a live metadata sidebar

Architecture

Component	Technology
Package management	uv (or pip/venv)
MCP server	FastMCP
REST API	FastAPI
Content UI	HTML/CSS (FastAPI)
Semantic search	numpy + Pydantic AI (optional)
Containerization	Docker + Compose
Persistence	Filesystem (volume mount)

Quick Start

Claude Desktop Extension (one-click install)

The fastest way to use Stash-MCP with Claude Desktop is the .mcpb Desktop Extension:

1. Download stash-mcp.mcpb from the latest release
2. Double-click the file — Claude Desktop opens the installer
3. Set your Content Directory (the folder where your documents live)
4. Optionally enable Git Tracking or Semantic Search
5. Click Install — the Stash icon appears alongside tool calls in Claude

Requirements: uv must be installed and on your PATH.

Docker Compose (recommended for servers)

docker-compose up -d        # start
docker-compose logs -f      # tail logs
docker-compose down         # stop

Endpoints:

Endpoint	Purpose
http://localhost:8000/ui	Web UI
http://localhost:8000/mcp	MCP (Streamable HTTP)
http://localhost:8000/api/...	REST API
http://localhost:8000/api/health	Health check

Your content is persisted in ./content.

Local development

uv sync                       # install deps
uv run -m stash_mcp.main      # run the server
uv run pytest                 # run tests
uv run ruff check .           # lint

Connecting MCP clients

Once the server is running, connect Claude Desktop, Claude Code, Cursor, or any other MCP client using one of the methods below.