elisp-dev-mcp: MCP Server for Agentic Elisp Development

Overview

elisp-dev-mcp is an Emacs package that provides an MCP (Machine Code Protocol) server for agentic Elisp development. It enables AI agents to assist with Elisp coding tasks by providing a structured API to interact with Emacs and manipulate Elisp code.

This package leverages mcp-server-lib.el for the underlying MCP infrastructure.

Installation

From MELPA:

M-x package-install RET elisp-dev-mcp RET

Usage

Registering with an MCP Client

After mcp-server-lib has been properly installed (including M-x mcp-server-lib-install), register elisp-dev-mcp with your MCP client:

claude mcp add -s user -t stdio elisp-dev -- ~/.emacs.d/emacs-mcp-stdio.sh --init-function=elisp-dev-mcp-enable --stop-function=elisp-dev-mcp-disable

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

Available MCP Handlers

Elisp Function Documentation

• Name: elisp-describe-function
• Description: Get full documentation for an Emacs Lisp function
• Parameters:
  • function: The name of the function to describe (string)
• Returns:
  • description: The function’s documentation (string)
  • or error: Error message if something went wrong (string)

Elisp Function Definition

• Name: elisp-get-function-definition
• Description: Get the source code definition of an Emacs Lisp function
• Parameters:
  • function: The name of the function to retrieve (string)
• Returns:
  • For Elisp functions:
    • source: The function’s source code including header comments if present (string)
    • file-path: Path to the file where the function is defined (string)
    • start-line: First line number of the definition including header comments (1-based integer)
    • end-line: Last line number of the definition (1-based integer)
  • For C-implemented functions:
    • is-c-function: Boolean indicator that this is a C function (always true)
    • function-name: The name of the function (string)
    • message: A message indicating the function is implemented in C source code (string)

Elisp Variable Description

• Name: elisp-describe-variable
• Description: Get information about an Emacs Lisp variable without exposing its value
• Parameters:
  • variable: The name of the variable to describe (string)
• Returns:
  • name: Variable name (string)
  • bound: Whether variable is currently bound (boolean, false for declared but unbound variables)
  • value-type: Type of the value (string, e.g. “cons”, “string”, “integer”)
  • documentation: Variable documentation or null if none (string or null)
  • source-file: Path to the file where the variable is defined (string)
  • is-custom: Whether it’s a customizable variable (boolean)
  • custom-group: The custom group this variable belongs to (string, only present for custom variables)
  • custom-type: The custom type specification (string, only present for custom variables)
  • is-obsolete: Whether the variable is marked obsolete (boolean)
  • obsolete-since: Version when the variable became obsolete (string, only present if obsolete)
  • obsolete-replacement: Suggested replacement for the obsolete variable (string, only present if obsolete)
  • is-alias: Whether the variable is an alias for another variable (boolean)
  • alias-target: The variable this is an alias for (string, only present if alias)
  • is-special: Whether the variable is a special (dynamically scoped) variable (boolean)
  • or error: Error message if something went wrong (string)

Elisp Info Documentation Lookup

• Name: elisp-info-lookup-symbol
• Description: Look up Elisp symbols in Info documentation and return the complete documentation node
• Parameters:
  • symbol: The Elisp symbol to look up (string)
• Returns:
  • found: Whether documentation was found (boolean)
  • symbol: The symbol that was looked up (string)
  • node: The Info node name containing the documentation (string, when found)
  • manual: The Info manual name, typically ‘elisp’ (string, when found)
  • content: The complete Info node content including all examples, cross-references, and related information (string, when found)
  • info-ref: Info reference like ‘(elisp)Node Name’ for direct access (string, when found)
  • message: Error or not-found message (string, when not found)

Elisp Source File Reader

• Name: elisp-read-source-file
• Description: Read Elisp source files from Emacs system directories or ELPA packages
• Parameters:
  • file-path: Absolute path to .el file (string)
• Returns:
  • The complete file contents as a string
  • or error: Error message if file not found, invalid format, or access denied (string)
• Examples:
  • "/opt/homebrew/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/files.el" - Read system file
  • "/Users/name/.emacs.d/elpa/package-1.0/package.el" - Read ELPA package
• Security:
  • Only reads from Emacs system lisp directories and ~/.emacs.d/elpa/
  • Rejects paths with .. traversal
  • Resolves symlinks to prevent escaping allowed directories
• Features:
  • Transparently handles .el.gz compressed files
  • Works directly with paths from elisp-get-function-definition
  • Returns complete file contents as string

License

This project is licensed under the GNU General Public License v3.0 (GPLv3) - see the LICENSE file for details.