Getting started

Zephr is a local-first MCP server. It runs on your machine via stdio JSON-RPC, stores evidence in a SQLite file per worktree, and exposes exactly eight tools to your coding agent. No account, no cloud, no telemetry.

Prerequisites

Install

Zephr ships as a single npm package with native sqlite-vec bundled per platform:

npx zephr-mcp

Or install globally for persistent access:

npm install -g zephr-mcp

Configure Claude Code

Add Zephr to your Claude Code MCP configuration. The server runs over stdio and needs a database path (defaults to :memory: if unset):

{
  "mcpServers": {
    "zephr": {
      "command": "npx",
      "args": ["zephr-mcp"],
      "env": {
        "ZEPHR_DB_PATH": "~/.zephr/store.db"
      }
    }
  }
}

Configure Cursor

Cursor supports MCP servers via its settings. Add the same configuration to your Cursor MCP config file:

{
  "mcpServers": {
    "zephr": {
      "command": "npx",
      "args": ["zephr-mcp"],
      "env": {
        "ZEPHR_DB_PATH": "~/.zephr/store.db"
      }
    }
  }
}
One database per worktree. Zephr scopes beliefs to a git worktree. Each worktree gets its own evidence graph. The ZEPHR_DB_PATH env var sets the primary database location; Zephr creates per-worktree tables within it.

The eight tools

Zephr exposes exactly eight MCP tools. This surface is frozen — a ninth tool is never added (ADR-Z-06). New capability routes through action enums or optional arguments on existing tools.

Admin token (optional)

Destructive operations (zephr_admin.purge, zephr_admin.migrate) require a capability minted from ZEPHR_ADMIN_TOKEN:

export ZEPHR_ADMIN_TOKEN="your-secret-token"
npx zephr-mcp

Without the token, zephr_admin.stats (read-only) still works. Purge and migrate are refused.

Architecture

Zephr uses a local SQLite database with FTS5 for lexical search and sqlite-vec for semantic retrieval. The hybrid fusion uses reciprocal rank (RRF). Every recalled belief carries a full provenance chain and bi-temporal recording. The store, read view, and admin capability are separated per ADR-Z-02.

Further reading