#+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