Skip to main content
Glama

#+title: ragmacs-mcp #+author: Lander M. Kerbey #+options: toc:t num:nil

An MCP server that gives LLMs live introspective access to a running Emacs instance. It exposes tools for reading documentation, browsing Info manuals, inspecting source code, and querying completions — all against your actual running Emacs environment.

The inspiration for this MCP is due to [[https://github.com/positron-solutions][Positron Solutions]], who created [[https://github.com/positron-solutions/ragmacs/tree/master][ragmacs]]. This is as much of a straight port to MCP as my limited ability allows at present.

  • Rationale

Given how easy it is to set up =ragmacs= via standard Emacs configuration, why bother with porting it to MCP? In the course of my day job, I have identified a number of workflows for which LLMs with tool-calling capabilities are very well suited, but the scope of the projects are such that the token consumption that comes with the necessary tool use would ramp up AI spend too much. Following on from articles by [[https://www.anthropic.com/engineering/code-execution-with-mcp][Anthropic]] and [[https://blog.cloudflare.com/code-mode/][Cloudflare]], I've been tinkering with MCP-based code-execution workflows. This is meant to facilitate that.

  • Prerequisites

** Emacs

You need a running Emacs with a server started. Add this to your Emacs config:

#+begin_src emacs-lisp (require 'server) (unless (server-running-p) (server-start)) #+end_src

Or start it interactively with M-x server-start.

** orderless

The completion tools (function_completions, command_completions, variable_completions) require the [[https://github.com/oantolin/orderless][orderless]] package. Install it via your package manager of choice, for example with use-package:

#+begin_src emacs-lisp (use-package orderless) #+end_src

** emacsclient

emacsclient must be on your PATH. Verify this works before proceeding:

#+begin_src bash emacsclient --eval "(emacs-version)" #+end_src

** C source (optional)

function_source and variable_source can retrieve source code for C built-ins if the Emacs C source is available on disk. If you are using a packaged Emacs binary, you may need to install an additional package such as emacs-src to make this work. If C source is unavailable, the tools return a helpful message explaining the situation rather than failing silently.

  • Installation

#+begin_src bash npm install npm run build #+end_src

  • Configuration

Add the following to your MCP client configuration. The exact file location depends on your client — for mcpproxy it is typically =~/.mcpproxy/mcp_config.json=:

#+begin_src json "mcpServers": [ { "name": "ragmacs", "command": "node", "args": ["ragmacs-mcp/dist/index.js"], "protocol": "stdio", "enabled": true } ] #+end_src

If you have multiple Emacs servers running and need to target a specific one, set the EMACS_SOCKET_NAME environment variable:

#+begin_src json "mcpServers": [ { "name": "ragmacs", "command": "node", "args": ["ragmacs-mcp/dist/index.js"], "protocol": "stdio", "enabled": true, "env": { "EMACS_SOCKET_NAME": "/run/user/1000/emacs/server" } } ] #+end_src

  • Tools

| Tool | Description | |------------------------+-----------------------------------------------| | elisp_eval | Evaluate an arbitrary Elisp expression | | symbol_exists | Check if a symbol exists in obarray | | load_paths | Return Emacs load paths | | list_features | Return loaded features | | list_manuals | List available Info manuals | | list_manual_nodes | List nodes within a manual | | manual_node_contents | Read the contents of a manual node | | check_feature | Check if a feature is loaded or available | | library_source | Read the full source of an Elisp library | | symbol_manual_section | Find the manual section for a symbol | | function_source | Read the source code of a function | | variable_source | Read the source code of a variable definition | | variable_value | Read the current global value of a variable | | function_documentation | Read the docstring of a function | | variable_documentation | Read the docstring of a variable | | function_completions | List functions matching a prefix | | command_completions | List commands matching a prefix | | variable_completions | List variables matching a prefix |

  • Development

#+begin_src bash npm test # run tests (requires a running Emacs) npm run build # compile TypeScript npm start # run the server #+end_src

Available Tools

18 tools
check_featureB

Check whether a specific feature is loaded or available.

Inputs: feature (required).

command_completionsB

Return all interactive commands matching a prefix.

Inputs: command_prefix (required).

elisp_evalC

Evaluate an arbitrary Elisp expression and return the result.

Inputs: expression (required).

function_completionsC

Return all function names matching a prefix using orderless.

Inputs: function_prefix (required).

function_documentationB

Return the docstring for a function or macro.

Inputs: function (required).

function_sourceB

Return the source code of a function or macro.

Inputs: function (required).

library_sourceB

Return the full source code of an Elisp library.

Inputs: library (required).

list_featuresA

Return the list of currently loaded Emacs features.

Inputs: no named parameters.

list_manual_nodesB

Return all node names within a given manual.

Inputs: manual (required).

list_manualsB

Return a list of available Info manual names.

Inputs: no named parameters.

load_pathsB

Return the user's Emacs load paths.

Inputs: no named parameters.

manual_node_contentsB

Return the full text of a node in an Info manual.

Inputs: manual_name (required), node (required).

symbol_existsB

Check if a symbol exists in obarray. Returns symbol name or nil.

Inputs: symbol (required).

symbol_manual_sectionC

Return the manual section that documents a given symbol.

Inputs: symbol (required).

variable_completionsC

Return all variables matching a prefix using orderless.

Inputs: variable_prefix (required).

variable_documentationC

Return the docstring for a defvar or defcustom.

Inputs: variable (required).

variable_sourceC

Return the source code of a defvar or defcustom.

Inputs: variable (required).

variable_valueC

Return the current global value of a variable.

Inputs: variable (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap in completion tools (function_completions, variable_completions, command_completions) and source/documentation tools (function_source vs library_source, function_documentation vs variable_documentation) that could cause mild confusion. However, the descriptions clarify the specific targets (functions vs variables vs commands), preventing major misselection.

    Naming Consistency5/5

    Tool names follow a highly consistent snake_case pattern with clear verb_noun structures (e.g., list_features, check_feature, elisp_eval). The naming is uniform across all tools, making it easy to predict and understand their functions without ambiguity.

    Tool Count4/5

    With 18 tools, the count is slightly high but reasonable for the domain of Emacs interaction and RAG, covering features, completions, documentation, source code, and manuals. It feels comprehensive without being overwhelming, though it borders on the heavier side for typical MCP servers.

    Completeness5/5

    The tool set provides complete coverage for interacting with Emacs: checking and listing features, evaluating code, retrieving completions, accessing documentation and source code for functions and variables, and navigating manuals. There are no obvious gaps; agents can perform a full range of queries and operations within this domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to interact with Clojure REPLs for evaluating code, performing structural edits with bracket balancing, and looking up symbol documentation. Transforms AI coding assistants into interactive programming partners with access to runtime evaluation and real data structures.
      66
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables LLMs to inspect and test other MCP servers by listing and calling their tools, reading resources, and getting prompts. Supports stdio, SSE, and HTTP transports for both local and remote MCP server inspection.
      7
      4 npm
      1
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      Provides AI assistants with live access to a Gerbil Scheme environment to evaluate expressions, look up module exports, and check syntax. It enables real-time interaction with the gxi runtime for macro expansion and symbol searching.
      6
      1
      -