slopmacs

jjtolton/slopmacs

3.1

If you are the rightful owner of slopmacs and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Slopmacs integrates Claude with Emacs using the Model Context Protocol (MCP) for seamless interaction.

Tools
20
Resources
0
Prompts
0

Slopmacs

MCP (Model Context Protocol) server that integrates Claude with Emacs via S-expression evaluation.

What is Slopmacs?

Slopmacs allows AI assistants like Claude to directly interact with your Emacs instance through S-expression evaluation. It provides a minimal, flexible interface for reading code, manipulating buffers, and integrating with Claude Code workflows.

Features

  • Single Eval Tool - Flexible S-expression evaluation for maximum control
  • Multi-Region Support - Mark and read multiple code regions across buffers
  • Claude Code Integration - Custom slash commands for seamless workflow
  • Unlimited Output - No truncation of large outputs (configurable)
  • Server Management - Built-in health monitoring and auto-restart capabilities
  • Safe Evaluation - Sandboxed S-expression execution with error handling
  • Automatic Reconnection - Resilient to Emacs restarts with automatic retry logic

MCP Tools

as_user_eval

The core tool for evaluating arbitrary Emacs Lisp expressions:

as_user_eval("(buffer-name)")  # Returns current buffer name
as_user_eval("(+ 1 2)")        # Returns "3"
as_user_eval("(find-file \"/path/to/file.el\")")  # Opens a file

This single tool provides maximum flexibility - any Emacs operation can be performed through S-expression evaluation.

Emacs Extensions

Multi-Region Package

Mark and manage multiple "pseudo-regions" across different buffers:

  • C-c m a - Add current region as pseudo-region
  • C-c m c - Clear all pseudo-regions
  • C-c m l - List all pseudo-regions
  • C-c m d - Delete a specific pseudo-region

Pseudo-regions persist when switching buffers and can all be read at once using the /read-emacs command.

See for details.

Claude Code Commands

/read-emacs

Reads all selected regions from Emacs:

  • Primary active region
  • Secondary selection
  • All pseudo-regions marked with C-c m a

See for details.

Quick Start

See for detailed setup instructions.

# 1. Install dependencies
pip install fastmcp emacs-porthole

# 2. Install Emacs components
# Add to your Emacs init file:
(load "~/.emacs.d/customizations/slopmacs.el")
(load "~/.emacs.d/customizations/setup-multi-region.el")

# 3. Copy files
cp slopmacs.el ~/.emacs.d/customizations/
cp elisp/*.el ~/.emacs.d/customizations/
cp claude-commands/*.md ~/.claude/commands/

# 4. Add to Claude Code
claude mcp add --scope user slopmacs python /path/to/slopmacs/server.py

# 5. Start Emacs server
M-x slopmacs-start-server

# 6. Start using it!
# Mark regions with C-c m a, then run /read-emacs in Claude Code

Architecture

┌─────────────────────┐
│   Claude Code       │
│   (MCP Client)      │
└──────────┬──────────┘
           │ MCP Protocol (stdio)
           ▼
┌─────────────────────┐
│   server.py         │
│   (FastMCP Server)  │
└──────────┬──────────┘
           │ Porthole RPC
           ▼
┌─────────────────────┐
│   Emacs             │
│   (slopmacs.el)     │
└─────────────────────┘

Usage Examples

For AI Assistants

# Evaluate any Emacs Lisp expression
as_user_eval("(buffer-name)")
as_user_eval("(find-file \"/path/to/file.el\")")
as_user_eval("(goto-line 42)")
as_user_eval("(search-forward \"TODO\")")

# Read buffer contents
as_user_eval("(buffer-substring-no-properties (point-min) (point-max))")

# Get multi-region info
as_user_eval("(multi-region-get-all-formatted)")

For Users

;; Start/stop server
M-x slopmacs-start-server
M-x slopmacs-stop-server

;; Mark multiple regions
C-c m a  ; Add region as pseudo-region
C-c m l  ; List all pseudo-regions
C-c m c  ; Clear all pseudo-regions

Workflow Example

  1. In Emacs: Select code in file A, press C-c m a
  2. In Emacs: Switch to file B, select code, press C-c m a
  3. In Claude Code: Run /read-emacs
  4. Claude reads all marked regions from both files at once!

Documentation

  • - Setup guide for humans
  • - Setup guide for AI assistants
  • - Fix output truncation
  • - Health monitoring setup
  • - Multi-region package documentation
  • - Claude Code commands

Requirements

  • Emacs: 28.1 or later
  • Python: 3.8 or later
  • Python Packages: fastmcp, emacs-porthole
  • Emacs Packages: porthole

Why "Slopmacs"?

A tongue-in-cheek name for pragmatic Emacs automation. It gets the job done.

License

MIT License - see file for details.

Contributing

Contributions welcome! This is a simple project - just submit a PR.