ragmacs-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ragmacs-mcp show me the source code for the `find-file` function"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
#+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 toolscheck_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
Scored across 18 tools
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.
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.
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.
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
Related MCP Connectors
Read-only HopBase AI gateway tools: models, limits, docs search, balance and usage for your API key.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Search and inspect source-pinned agent skills, plugins and tools through a free public MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceElisp (Emacs Lisp) development support tools, running in Emacs49GPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables 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.66MIT
- AlicenseAqualityBmaintenanceEnables 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.74 npm1MIT
- FlicenseAqualityCmaintenanceProvides 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.61-