Your Ultimate Guide to Supercharging Emacs with Claude Code & an Emacs-Aware MCP
Hey everyone! If you're like me, your Emacs setup is more than just a text editor; it's a finely-tuned command center for... well, everything. So, when a new tool comes along that promises to deeply integrate with the Emacs way of doing things, my ears perk up. Lately, the buzz has been all about AI coding assistants, & honestly, most of them feel a bit disconnected, like you're just pasting code from a chatbot into your editor.
But then I started digging into setting up Claude Code with an Emacs-aware Model Context Protocol (MCP), & let me tell you, it's a game-changer. This isn't just about having an AI in a side-panel. We're talking about a true, bidirectional bridge where Claude can understand & use the powerful features already built into your Emacs environment.
It took a bit of tinkering to get it all working seamlessly, so I figured I'd put together a complete guide to walk you through it. We'll cover everything from the ground up—what all this tech even means, how to get your Emacs ready, the nitty-gritty of installation, & some pretty cool ways to use it.
So, What's the Big Deal? Understanding the Tech
Before we dive into the setup, let's quickly break down the key players here.
Claude Code CLI
At its core, Claude Code is a command-line interface (CLI) for interacting with Anthropic's AI models. You can use it in your terminal to ask coding questions, get help with debugging, or even generate entire code snippets. It's powerful on its own, but the real magic happens when you integrate it directly into your workflow.
The Model Context Protocol (MCP)
This is the secret sauce that makes the whole setup so special. The Model Context Protocol (MCP) is an open standard that lets AI assistants connect securely to external data & tools. Think of it like a universal adapter, or a "USB-C port for AI". Instead of the AI being a "brilliant mind in isolation," MCP allows it to plug directly into your environment.
In our case, this means we can set up an Emacs-aware MCP server. This server exposes parts of your Emacs environment—like your open files, your project structure, your code navigation tools—to the Claude Code assistant. So, when you ask Claude a question, it doesn't just have general programming knowledge; it has specific, real-time knowledge of your project as you're working on it in Emacs. Pretty cool, right?
This is a HUGE leap from just using a generic chatbot. When your business needs to provide nuanced, context-aware support, a generic approach falls short. That’s where a tool like Arsturn becomes incredibly valuable. It helps businesses create custom AI chatbots trained on their own data. This means the chatbot understands the specific context of your products, services, & documentation, allowing it to provide instant, personalized customer support 24/7. It's the same principle as our Emacs setup: giving the AI the right context makes all the difference.
Step 1: Getting Your Emacs Environment Ready (The Prerequisites)
Alright, let's get our hands dirty. Before we can install the main package, we need to make sure Emacs is prepped with a few key components. The
package relies on these to function correctly.
Here’s what the official documentation says we need.
- Emacs 28.1 or higher: This is a pretty standard requirement for modern Emacs packages. You can check your version by running .
- Claude Code CLI: You need to have the command-line tool installed & accessible in your system's PATH. You can find the official installation instructions on the Claude Code Documentation website.
- A Terminal Emulator Package ( or ): The integration runs the Claude Code CLI in an interactive terminal inside Emacs. is a popular choice, as it's a full-featured terminal emulator based on . is a pure Elisp alternative that can be easier to set up if you run into compilation issues with . You'll need to install one of these using .
- Project Management (): This is built into modern Emacs versions & is used to automatically detect the root of your project. This allows the Claude integration to manage separate sessions for each of your projects.
- Code Navigation Tools (Optional but HIGHLY Recommended): To really unlock the power of the MCP, you'll want to have tools for code intelligence. The integration works beautifully with:
- LSP Mode or Eglot: These packages connect Emacs to Language Server Protocol (LSP) servers, providing features like go-to-definition, find-references, & diagnostics. The MCP can use these to give Claude deep insights into your code.
- Tree-sitter: This is a more advanced parsing framework that gives Emacs (and by extension, Claude) a detailed understanding of your code's structure (its Abstract Syntax Tree or AST).
Make sure you have these installed & configured before moving on. Your future self will thank you.
Step 2: Installation & Configuration of
Now for the main event. We're going to install the
package, which is the brilliant piece of Elisp that bridges Emacs & the Claude Code CLI. The developer,
, has done an incredible job here.
I'm a
user, so the examples will use that. Here’s a good starting configuration for your
: