emacs-runtime-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., "@emacs-runtime-mcp What Emacs version is running, and which buffer am I in right now?"
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.
emacs-runtime-mcp
A small MCP stdio server that evaluates one Emacs Lisp form in an
already-running Emacs instance. It exposes exactly one tool, emacs_eval;
agents discover built-in, package, and user-defined capabilities from the live
runtime instead of loading a generated command catalog.
Security
This package provides arbitrary code execution with the permissions of your Emacs process and user account. Use it only with trusted local MCP clients.
It is not a sandbox, access-control boundary, transaction system, or safe
network service. A connected client can read, modify, or delete user-accessible
data and control Emacs. A request timeout only terminates emacsclient; Lisp
already accepted by Emacs may continue running. Output limits do not prevent
Emacs from constructing a large value in memory.
See SECURITY.md before enabling the server.
Related MCP server: Localbridge-MCP
Requirements
Component | Supported |
Node.js | 20 or newer |
Emacs and | 28 or newer, preferably from the same installation |
Transport | Local stdio MCP |
Platform | macOS and Linux |
The server never starts Emacs. Start a daemon yourself (emacs --daemon) or
enable server-mode in the Emacs instance you want to control.
Install
From npm after a release:
npm install --global emacs-runtime-mcpFrom a source checkout:
pnpm install
pnpm build
node dist/cli.js --helpMCP Client Configuration
For a global installation:
{
"mcpServers": {
"emacs": {
"command": "emacs-runtime-mcp"
}
}
}For a named daemon such as emacs --daemon=work:
{
"mcpServers": {
"emacs": {
"command": "emacs-runtime-mcp",
"args": ["--socket-name", "work"]
}
}
}An explicit server file is also supported:
{
"mcpServers": {
"emacs": {
"command": "emacs-runtime-mcp",
"args": ["--server-file", "/absolute/path/to/server-file"]
}
}
}--socket-name and --server-file are mutually exclusive. Every invocation
passes --alternate-editor=false, so an unavailable server fails instead of
starting another editor or daemon.
Options And Environment
CLI option | Environment variable | Default |
|
|
|
|
| default server |
|
| unset |
|
|
|
|
|
|
CLI values override the corresponding environment value. Supplying both kinds of server selector is a startup error.
Tool
emacs_eval accepts:
{
"expression": "(list (emacs-version) (buffer-name))",
"timeout_ms": 10000,
"max_output_chars": 65536
}expression must contain exactly one readable Emacs Lisp form. Node validates
the request shape and numeric limits; the selected Emacs runtime performs Lisp
reading and rejects trailing non-whitespace content before evaluation.
Supported limits:
expression: 1 to 262,144 Unicode code pointstimeout_ms: 100 to 120,000max_output_chars: 1 to 262,144combined subprocess stdout/stderr: fixed 1 MiB hard ceiling
The tool returns the prin1-to-string representation, not an automatic
JSON conversion of the Lisp value.
Success
{
"ok": true,
"value": "(\"GNU Emacs 31.1\" \"notes.org\")",
"truncated": false,
"original_chars": 31,
"elapsed_ms": 4
}original_chars is always present. max_output_chars limits only value.
Counts use Emacs string characters after printing, not UTF-8 bytes or grapheme
clusters.
Failure
{
"ok": false,
"error": {
"code": "elisp_error",
"message": "Symbol's value as variable is void: missing",
"data": {
"symbol": "void-variable"
}
},
"elapsed_ms": 3
}Stable codes are invalid_request, invalid_expression,
emacs_unavailable, elisp_error, evaluation_timeout,
output_too_large, bridge_protocol_error, and internal_error.
MCP results carry the same envelope in structuredContent and JSON text
content. Failed envelopes set isError: true.
Agent Discovery Skill
skills/emacs-live/SKILL.md teaches agents to:
inspect explicit live buffer, window, mode, and project context;
discover symbols with Emacs introspection;
review signatures, interactive prompts, source, and side effects;
invoke one explicit operation;
verify its postcondition.
The Skill contains reusable discovery patterns, not a command inventory.
Troubleshooting
emacs_unavailable: verify the daemon name or server file withemacsclient --alternate-editor=false --socket-name NAME --eval t.invalid_expression: submit one form; wrap multiple intended operations inprogn.elisp_error: inspecterror.data.symboland the message, then inspect the candidate function and runtime context.evaluation_timeout: assume runtime state is unknown. Run a read-only health probe and inspect relevant state before another mutation.output_too_large: narrow the query. Increasingmax_output_charscannot exceed the fixed transport ceiling.bridge_protocol_error: confirmemacsclientand Emacs are compatible and that no wrapper output is being modified.
All server diagnostics go to stderr. Stdout is reserved for MCP JSON-RPC.
Development
pnpm check
pnpm test:integration
pnpm build
pnpm packIntegration tests create a random named emacs -Q daemon with temporary state
and always target it explicitly; they never use the developer's default server.
Licensed under MIT.
Available Tools
1 toolemacs_evalEvaluate Emacs LispC
Evaluate exactly one Emacs Lisp form in an already-running trusted local Emacs server.
Inputs: expression (required), timeout_ms, max_output_chars. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
There is only one tool, so there is no possibility of selecting the wrong one. Its purpose—evaluating a single Emacs Lisp form—is unambiguous.
The single name 'emacs_eval' follows a clear namespace_verb convention in snake_case, which is readable and predictable. With only one tool there is no pattern to verify against, so it cannot be judged fully consistent.
A single tool is thin for a server whose stated scope is an Emacs runtime. It earns its place, but the surface is minimal enough that agents will hit its limits quickly.
Evaluation of one form at a time is functional but leaves notable gaps: no batch evaluation, no file loading or buffer inspection, and no way to explore server state. The core operation exists, but the surrounding lifecycle is largely absent.
Maintenance
Related MCP Connectors
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
Single-connection MCP gateway discovering and executing 490+ verified MCP & A2A tools.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Your team's custom tools and skills in every agent, through one MCP connection.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceIt enables local MCP clients to interact with the live Positron R or Python session, supporting variable inspection, silent evaluation, and state-changing execution.2MIT
- AlicenseAqualityBmaintenanceLocalBridge MCP is a bridge between an online AI chats and your computer. Most online AI chats can reason, and write code, but they normally cannot touch the local files, terminals, and scripts that make real work happen. This gives a trusted assistant a controlled doorway into a machine you own, so it can inspect files, edit text, search a project, run tests, use Git, and operate a shell.173Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables secure discovery and invocation of sandboxed filesystem, repository inspection, and utility tools through a unified MCP client with schema validation, timeouts, and execution traces.-
- FlicenseNot gradedqualityCmaintenanceEnables agents to search and call ranked MCP servers and registered agents through one remote endpoint, delegate tasks, and use hosted tools without installation while keeping credentials per-call and unstored.-