eval-elisp-mcp

• Overview
• Installation
  • Manual
  • With straight.el
  • Emacs use-package (as of Emacs 30+)
  • In Doom Emacs
• Security
• Usage
• Tools
  • eval_elisp
  • get_source

Overview

eval-elisp-mcp is an Emacs MCP server exposing two tools: eval_elisp and get_source.

The tool evaluates one Emacs Lisp form in the currently running Emacs instance and returns the result formatted with pp-to-string. The last three successful results are available as *, **, and ***.

Evaluation happens in a hidden frame, so it generally shouldn't interfere with your UI if you are using the same emacs instance.

If parinfer-rust-mode is installed, it will use it to try and autofix parentheses.

This package uses mcp-server-lib.el for MCP transport and tool registration.

Installation

Manual

Clone this repository and add it to your load path.

(add-to-list 'load-path "/path/to/eval_elisp_mcp")
(require eval-elisp-mcp)

With straight.el

(use-package eval-elisp-mcp
  :straight (eval-elisp-mcp :type git :host codeberg :repo "sczi/eval-elisp-mcp"))

Emacs use-package (as of Emacs 30+)

(use-package eval-elisp-mcp
  :vc (:url "https://codeberg.org/sczi/eval-elisp-mcp.git" :rev :newest))

In Doom Emacs

add to packages.el and run doom sync

(package! eval-elisp-mcp
  :recipe (:host codeberg :repo "sczi/eval-elisp-mcp"))

Security

eval_elisp executes arbitrary Emacs Lisp. Run it inside a sandbox, for example incus as described in the security section of opencode.el

Usage

Install and configure mcp-server-lib first, including M-x mcp-server-lib-install.

Register this MCP server in opencode.json with:

"mcp": {
    "emacs": {
        "type": "local",
        "command": ["/home/user/.emacs.d/emacs-mcp-stdio.sh",
                    "--init-function=eval-elisp-mcp-enable",
                    "--stop-function=eval-elisp-mcp-disable",
                    "--server-id=emacs"],
        "codemode": false
    }
}

Before using the MCP server, start request handling in Emacs with M-x mcp-server-lib-start. Stop it with M-x mcp-server-lib-stop when done.

I recommend configuring the MCP with "codemode": false, as codemode trims descriptions so it misses part of the instructions on how to use the tool. And it doesn't need a js interpreter to compose different functions, when it already has an elisp one.

Tools

eval_elisp

• Name: eval_elisp
• Description: Evaluate one Emacs Lisp form in the current Emacs instance
• Parameters:
• expression: Emacs Lisp source containing exactly one form. Use (progn ...) for multiple forms.
• Returns: the evaluated result formatted with pp-to-string
• Result history: the last three successful results are available as *, **, and ***

get_source

• Name: get_source
• Description: Return the source code defining a function, macro, variable or face
• Parameters:
• symbol: name of the function, macro, variable or face
• type (optional): one of function (also used for macros), variable or face. If omitted, all definitions of the symbol are returned.
• Returns: each definition's source in the same format as opencode's read tool: <path>, <type> and <content> with numbered lines. A definition with no source file (e.g. evaluated interactively) is returned as its pretty-printed symbol-function, symbol-value or face-default-spec. Definitions in C are only available when find-function-C-source-directory is set.