@bimawa/emacsclient-mcp

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

Packages

Package details

extension

Install @bimawa/emacsclient-mcp from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@bimawa/emacsclient-mcp
Package
@bimawa/emacsclient-mcp
Version
1.0.0
Published
Jul 13, 2026
Downloads
not available
Author
bimawa
License
MIT
Types
extension
Size
13.4 MB
Dependencies
1 dependency · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./extension/index.ts"
  ],
  "image": "https://raw.githubusercontent.com/bimawa/emacsclient-mcp/main/docs/preview.png"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

emacsclient-mcp

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

Crates.io npm License: MIT

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