emacs-mcp

An MCP (Model Context Protocol) server that bridges Claude Code with Emacs via emacsclient.

Features

Phase 1: Core (Buffer & Eval)

Tool	Description
emacs_eval	Execute arbitrary Elisp code
emacs_buffer_read	Read contents of a buffer
emacs_buffer_write	Write/replace content in a buffer
emacs_buffer_edit	Apply targeted edits (find and replace)
emacs_buffer_list	List all open buffers
emacs_buffer_switch	Switch to a buffer
emacs_buffer_create	Create a new buffer
emacs_buffer_kill	Close/kill a buffer

Phase 2: File & Project Operations

Tool	Description
emacs_file_open	Open a file (with optional line/column)
emacs_file_save	Save buffer to file
emacs_file_save_as	Save buffer to new path
emacs_file_info	Get file metadata
emacs_project_list	List known projects
emacs_project_current	Get current project info
emacs_project_switch	Switch to a project
emacs_project_files	List files in project
emacs_project_search	Search files by pattern
emacs_workspace_list	List workspaces/tabs
emacs_workspace_current	Get current workspace
emacs_workspace_switch	Switch workspace
emacs_workspace_create	Create new workspace
emacs_workspace_delete	Delete workspace
emacs_workspace_save	Save workspace state

Phase 3: Org-mode Integration

Tool	Description
emacs_org_read	Read org document (raw or parsed structure)
emacs_org_write	Write content to org buffer
emacs_org_heading_add	Add a new heading
emacs_org_heading_update	Update heading title/content
emacs_org_heading_delete	Delete a heading and subtree
emacs_org_heading_move	Move heading (up/down/promote/demote)
emacs_org_todo_set	Set TODO state for a heading
emacs_org_todo_list	List all TODO items
emacs_org_tag_set	Set tags for a heading
emacs_org_property_set	Set a property for a heading
emacs_org_export	Export to html/pdf/markdown/latex/ascii/odt
emacs_org_agenda	Query agenda (day/week/month)
emacs_org_capture	Create entry via capture template
emacs_org_search	Search org files (text/heading/tag/property)

Phase 4: Git/Magit Integration

Tool	Description
emacs_git_status	Get git status (staged, unstaged, untracked)
emacs_git_diff	Get diff (staged/unstaged/committed)
emacs_git_log	Get commit log
emacs_git_stage	Stage files for commit
emacs_git_unstage	Unstage files
emacs_git_commit	Create a commit
emacs_git_branch_list	List branches
emacs_git_branch_current	Get current branch
emacs_git_branch_checkout	Checkout a branch
emacs_git_stash_list	List stashes
emacs_git_stash_push	Create a stash
emacs_git_stash_pop	Pop a stash
emacs_git_blame	Show git blame for a file

Phase 5: Ediff & Comparison

Tool	Description
emacs_ediff_files	Compare two files (unified/context/side-by-side)
emacs_ediff_buffers	Compare two buffers
emacs_ediff_regions	Compare two text strings
emacs_ediff_3way	Three-way file comparison (for merges)
emacs_diff_summary	Get summary of differences

Resources

URI	Description
emacs://buffers	List of all open buffers
emacs://buffer/{name}	Contents of a buffer
emacs://projects	List of known projects
emacs://project/current	Current project info
emacs://project/{path}/files	Files in a project
emacs://workspaces	List of workspaces
emacs://workspace/current	Current workspace
emacs://org/agenda	Today's agenda items
emacs://org/todos	All TODO items
emacs://org/files	Org-agenda files
emacs://org/capture-templates	Available capture templates
emacs://git/status	Current git status
emacs://git/branch	Current branch info

Compatibility

• Vanilla Emacs: Uses project.el and tab-bar-mode
• Doom Emacs: Uses projectile and +workspace (auto-detected)

Prerequisites

1. Emacs 28+ with daemon support
2. Node.js 18+
3. Running Emacs daemon:

   emacs --daemon
   

Installation

npm install
npm run build

Configuration

Add to your Claude Code .mcp.json:

{
  "mcpServers": {
    "emacs": {
      "command": "node",
      "args": ["/path/to/emacs-mcp/dist/index.js"],
      "env": {
        "EMACS_SOCKET": "/run/user/1000/emacs/server",
        "EMACSCLIENT_PATH": "/usr/bin/emacsclient"
      }
    }
  }
}

Environment Variables

Variable	Description	Default
EMACS_SOCKET	Path to Emacs daemon socket	Auto-detect
EMACSCLIENT_PATH	Path to emacsclient binary	emacsclient
EMACS_TIMEOUT	Default timeout for operations (ms)	5000
EMACS_ORG_DIRECTORY	Org files directory	~/org

Usage Examples

Claude: Read the contents of the *scratch* buffer
> Uses emacs_buffer_read tool

Claude: List all open buffers
> Uses emacs_buffer_list tool

Claude: Evaluate (+ 1 2 3) in Emacs
> Uses emacs_eval tool

Claude: What projects do I have open?
> Uses emacs_project_list tool

Claude: Switch to workspace "main"
> Uses emacs_workspace_switch tool

Claude: Open /path/to/file.ts at line 42
> Uses emacs_file_open tool

Claude: Show me my TODO items
> Uses emacs_org_todo_list tool

Claude: Add a TODO heading "Review PRD" to notes.org
> Uses emacs_org_heading_add tool

Claude: What's on my agenda this week?
> Uses emacs_org_agenda tool

Claude: Export my notes.org to PDF
> Uses emacs_org_export tool

Claude: What's my git status?
> Uses emacs_git_status tool

Claude: Show me the recent commits
> Uses emacs_git_log tool

Claude: Stage all changes and commit
> Uses emacs_git_stage and emacs_git_commit tools

Claude: What branch am I on?
> Uses emacs_git_branch_current tool

Claude: Compare file.ts with file.ts.bak
> Uses emacs_ediff_files tool

Claude: Show me the differences between these two buffers
> Uses emacs_ediff_buffers tool

Claude: Do a three-way merge comparison
> Uses emacs_ediff_3way tool

Development

# Watch mode
npm run dev

# Run tests
npm test

# Lint
npm run lint

Roadmap

See PRD.md for full roadmap:

• [x] Phase 1: Core Infrastructure (MVP)
• [x] Phase 2: File & Project Operations
• [x] Phase 3: Org-mode Integration
• [x] Phase 4: Git/Magit Integration
• [x] Phase 5: Ediff & Advanced Features

License

MIT