emacsclient-mcp

Emacs MCP server + Pi extension — 22 Emacs tools for LLM-assisted editing, search, buffer management, and PR review.

What is this?

A Model Context Protocol (MCP) server that gives LLMs direct access to Emacs — no emacsclient binary needed. It communicates via Unix socket using the Emacs server protocol, implementing &-quoting as defined in emacsclient.c and server.el.

Comes with:

• Rust MCP binary — 22 tools over JSON-RPC stdio

• Pi extension — auto-spawns the binary, registers all tools

• PR review agent — 4-phase workflow (Setup → Analysis → Issues → Report)

Related MCP server: email-send-mcp

Quick Start

1. Install

# Option A: Pi package (recommended — gets extension + agent)
pi install npm:@bimawa/emacsclient-mcp

# Option B: Rust binary only (for other MCP clients)
cargo install emacsclient-mcp

# Option C: Homebrew (macOS)
brew install bimawa/tap/emacsclient-mcp

2. Start Emacs server

M-x server-start
;; or:
emacs --daemon

3. Reload Pi

/reload

Pi picks up the extension, spawns the binary, discovers 22 Emacs tools, and registers the emacs-pr-review agent.

Tools

PR Review Agent

Activate with /agent emacs-pr-review in Pi. The agent:

1. Setup — gets the diff, opens review buffer in org-mode, splits Emacs windows

2. Analysis — reads each changed file, applies review heuristics (R1–R4)

3. Findings — documents issues by severity: BLOCKER / CRITICAL / WARNING / SUGGESTION

4. Report — shows summary in Emacs, offers inline comments

Protocol

Implements the exact Emacs server protocol from server.el:

• Client sends first (no server greeting)

• Single-line commands: -auth KEY -eval EXPR\n

• &-quoting: spaces → &_, newlines → &n, leading - → &-, & → &&

• Response: -emacs-pid PID\n-print RESULT\n

Binary Resolution

The extension finds the binary in this order:

1. EMACS_MCP_BINARY environment variable

2. Pre-built binary alongside the extension (package distro)

3. ~/.cargo/bin/emacsclient-mcp (cargo install)

4. which emacsclient-mcp (PATH / Homebrew)

5. cargo run --release (dev mode)

Development

# Build the Rust binary
cargo build --release

# Run locally with Pi
pi -e ./extension/index.ts

# Test the MCP binary directly
echo '{"jsonrpc":"2.0","id":1,"method":"initialize",...}' | ./target/release/emacsclient-mcp

License

MIT © bimawa