Skip to content
selvedge

Add Selvedge to Claude Code

Claude Code has a first-class MCP CLI, so the fastest path is a single claude mcp add. There’s also a plugin-marketplace install and the auto-detecting selvedge setup wizard.

Before you start

Section titled “Before you start”

pip install selvedge gives you the selvedge CLI (selvedge setup, selvedge blame, and the selvedge prompt helper below):

Terminal window
pip install selvedge

The MCP config below launches the server with uvx instead of a bare selvedge-server, so it starts reliably even when your editor doesn’t share your shell’s PATH — it just needs uv installed. Prefer the global binary? Swap uvx --from selvedge selvedge-server for selvedge-server.

Add the MCP server

Section titled “Add the MCP server”

The fastest path — register the stdio server with one command:

Terminal window
claude mcp add selvedge -- uvx --from selvedge selvedge-server

Add --scope user to make it available across all your projects, or --scope project to write a shared .mcp.json you can commit so the whole team gets it. Local scope (the default) keeps it to you in the current project.

That writes the equivalent MCP config to ~/.claude.json (local/user scope) or .mcp.json at the project root (project scope):

{
  "mcpServers": {
    "selvedge": {
      "command": "uvx",
      "args": ["--from", "selvedge", "selvedge-server"]
    }
  }
}

Prefer not to touch config files? selvedge setup detects Claude Code and writes this for you (with a .bak first).

Plugin marketplace (Claude-Code-only alternative)

Section titled “Plugin marketplace (Claude-Code-only alternative)”
/plugin marketplace add masondelan/selvedge
/plugin install selvedge@selvedge

Run pip install selvedge first either way — the plugin wires the MCP server but does not install the Python package that provides selvedge-server.

Tell your agent when to call it

Section titled “Tell your agent when to call it”

Selvedge only captures the why if your agent knows to call it. Install the one-block instruction set into your project’s CLAUDE.md / .cursorrules:

Terminal window
selvedge prompt --install CLAUDE.md

It’s also a copy-paste block on the site: the Selvedge agent prompt block.

Verify

Section titled “Verify”

Run /mcp inside Claude Code (or claude mcp list in a terminal). selvedge should show as connected with its 8 tools.

If it doesn’t connect

Section titled “If it doesn’t connect”

If claude mcp list shows selvedge as failed, uvx (from uv) isn’t on the PATH Claude Code spawns with — install uv, then re-run. Prefer a global install? Register -- selvedge-server after pip install selvedge instead.

Next

Section titled “Next”