Emacs MCP

🚀 Emacs MCP - Model Context Protocol for Emacs

This package implements the Model Context Protocol (MCP) for Emacs, enabling LLMs to access information about the Emacs environment and configuration. It allows LLMs to assist in extending Emacs configuration and creating new packages without manual context specification.

🚀 Quick Start

This package implements the Model Context Protocol (MCP) for Emacs, extending the capabilities of LLMs to access information about the Emacs environment and configuration. Emacs MCP offers tools with details about loaded packages, available functions, key - bindings, documentation, etc. This allows LLMs to be used to extend Emacs configuration and create new packages without the user having to manually specify contextually relevant files.

📦 Installation

Standard Installation

Clone this repository and include the following code in your user init file (e.g., ~/.emacs.d/init.el or equivalent):

(add-to-list 'load-path "/path/to/emacs-mcp")
(require 'emacs-mcp)

Test your configuration using the model context protocol inspector:

npx @modelcontextprotocol/inspector emacs --batch --load '<path to your init file>' --eval '(emacs-mcp-run-stdio)'

Doom Emacs Configuration

Doom Emacs does not have an init file. To load user configuration before running in batch mode, you need to create a doomscript file that bootstraps the Doom Emacs environment and loads your configuration files.

You can create a file called ~/.config/doom/bin/emacs-mcp with the following content:

#!/usr/bin/env doomscript
(defcli! emacs-mcp ()
  (doom-modules-initialize)      ; initialize the module system
  (doom-initialize t)            ; bootstrap Doom as if this were an interactive session
  (doom-startup)                 ; load your modules and user config
  (emacs-mcp-run-stdio))         ; run the MCP server

(run! "emacs-mcp")

This ensures that the Emacs instance running the MCP server will access the same environment and modules as your interactive Doom Emacs instance.

You can then test your configuration using the following command:

npx @modelcontextprotocol/inspector ~/.config/emacs/bin/doomscript ~/.config/doom/bin/emacs-mcp

💻 Usage Examples

Basic Usage

Configure the MCP server for your LLM client by changing the mcp.json file as prescribed by your LLM client's documentation, such as Claude Code or Amazon Q Developer CLI.

{
  "mcpServers": {
    "emacs": {
      "command": "emacs",
      "args": [
        "--batch",
        "--load",
        "<path to your init file>",
        "--eval",
        "(emacs-mcp-run-stdio)"
      ]
    }
  }
}

Advanced Usage

If you are using Doom Emacs, you can use the following configuration:

{
  "mcpServers": {
    "emacs": {
      "command": "~/.config/emacs/bin/doomscript",
      "args": ["~/.config/doom/bin/emacs-mcp"]
    }
  }
}

📄 License

This project is licensed under the MIT license.