home / mcp / emacs mcp server

Emacs MCP Server

Provides a live MCP server to generate and execute Emacs Lisp inside a running Emacs process.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "vivekhaldar-emacs-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with",
        "smartfunc",
        "mcp",
        "run",
        "/Users/haldar/repos/gh/emacs-mcp-server/emacs_mcp_server.py"
      ],
      "env": {
        "EMACSCLIENT": "/your/path/to/emacsclient",
        "OPENAI_API_KEY": "REPLACE_WITH_YOUR_API_KEY"
      }
    }
  }
}

You can run a Model Context Protocol (MCP) server inside Emacs to generate and execute elisp code in a live Emacs process. This server enables you to generate elisp for tasks and then send it to Emacs for evaluation, making it easier to automate and extend your editing workflow.

How to use

To use this MCP server, you first set up an MCP client/runner and then connect it to your local Emacs instance. You will generate elisp code for your task, then hand it to Emacs to evaluate and apply. The server exposes two core tools you can leverage through your MCP client: generate_emacs_lisp_code to produce elisp for a given task, and execute_emacs_lisp_code to pass the generated code to a running Emacs via emacsclient for evaluation.

How to install

Prerequisites you need before installing this MCP server include a working Node.js and Python environment, since the setup relies on the MCP workflow and a Python script that runs the server.

Install dependencies and prepare the environment, then install and configure the MCP server for use with your editor. Follow these steps exactly to ensure the server runs correctly in inspector mode and is installable for your editor’s MCP client.

uv sync
source .venv/bin/activate
```

```sh
mcp dev emacs_mcp_server.py
```

```sh
mcp install emacs_mcp_server.py

Additional content

Configuration for editor integration is provided in a JSON block that Claude Desktop can use to locate and run the MCP server. You must include your API key and the full path to your Emacs client (emacsclient) in the environment section.

"Emacs-MCP-Server": {
      "command": "/Users/haldar/.local/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with",
        "smartfunc",
        "mcp",
        "run",
        "/Users/haldar/repos/gh/emacs-mcp-server/emacs_mcp_server.py"
      ],
      "env": {
          "OPENAI_API_KEY": "sk-xxxx",
          "EMACSCLIENT": "/your/path/to/emacsclient"
      }
    }

Notes, configuration, and troubleshooting

This server is designed to work with a running Emacs instance via emacsclient. Ensure that emacsclient is accessible in your PATH or specify the full path in the environment configuration. If you are using Claude Desktop or another MCP client, provide the exact runtime command and environment variables shown in the integration example to enable seamless startup and secure operation.

Available tools

generate_emacs_lisp_code

Generates elisp code for a given task to be executed inside Emacs.

execute_emacs_lisp_code

Sends generated elisp to a running Emacs instance via emacsclient for evaluation.