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)

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

Category	Tools
Eval	emacs_eval — run arbitrary Elisp
Buffers	emacs_list_buffers, emacs_create_buffer, emacs_set_buffer_content, emacs_get_buffer_content, emacs_save_buffer, emacs_kill_buffer
Navigation	emacs_find_file, emacs_switch_to_buffer, emacs_goto_line, emacs_get_cursor_position, emacs_get_line
Search	emacs_search, emacs_replace
Editing	emacs_insert_at_point, emacs_get_region, emacs_set_mark
Windows	emacs_split_window_right, emacs_split_window_below, emacs_other_window, emacs_delete_other_windows, emacs_display_in_other_window

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