Emacs MCP服务器

Emacs MCP 服务器

一个用Emacs Lisp实现的模型上下文协议（MCP）服务器，它使Claude Code CLI能够通过一系列全面的工具与Emacs进行交互，包括缓冲区管理、Org-mode操作、工作区控制以及Elisp调试功能。

概述

该项目提供了三个主要组成部分：

1. 主要入口点 （emacs-mcp.el) - 加载核心MCP框架
2. MCP服务器框架 （mcp-server.el， mcp-types.el) - 一个完整的MCP服务器实现，具备类型验证、安全特性以及用于定义工具的宏系统
3. 示例工具集 (example/mcp-tools.el) - 提供25+个可选的即用型工具，用于缓冲区管理、Org-mode操作、工作区控制和Elisp调试

该框架允许您为特定的Emacs工作流程创建自定义的MCP工具，同时示例工具提供了即时功能，并且可以选择性地加载。

安装

先决条件Emacs 27+， nc (netcat)，Claude 代码命令行界面 (CLI)

选项1：使用straight.el（推荐）

（工作进行中 - 正在测试此功能）

1. 使用straight.el进行安装:

   添加到您的 packages.el （适用于Doom）或等效设备：

   复制

    (package! emacs-mcp
    :recipe (:host github :repo "ElleNajt/emacs-mcp"
            :files ("*.el" "example/*.el" "mcp-proxy.sh" "agents/*.md" "post-build-hook.el")))
   
    ;; Post-build hook that loads the actual hook implementation after download
    (add-hook 'straight-use-package-post-build-functions
            (lambda (package)
                (when (string= package "emacs-mcp")
                (let ((hook-file (expand-file-name "post-build-hook.el" 
                                                    (straight--build-dir package))))
                    (when (file-exists-p hook-file)
                    (load hook-file nil nil t)
                    (message "emacs-mcp: Post-build setup completed"))))))
   

   添加到您的 config.el 或者初始化文件：

   复制

   (use-package! emacs-mcp
     :config
     ;; Optionally load example tools
     (require 'mcp-tools)
     
     ;; Start the MCP server
     (emacs-mcp-start-server))
   

   或者仅获取核心框架而不包含示例：

   复制

   (use-package! emacs-mcp
     :config
     ;; Start the MCP server (core framework only)
     (emacs-mcp-start-server))
   

选项2：手动安装（用于测试）

1. 克隆此仓库：

   复制

   git clone https://github.com/yourusername/emacs-mcp.git
   cd emacs-mcp
   

2. 尝试示例配置： 这个（或“该”） example/init-example.el 该文件提供了无需安装即可进行测试的完整配置。它应从仓库目录中运行：

   复制

   ;; Load from current directory (for testing only)
   (load-file "emacs-mcp.el")  ; This loads the core framework
   (require 'mcp-tools)        ; Optionally load example tools
   (emacs-mcp-start-server)
   

3. 在Claude代码命令行界面中安装:

   复制

   /path/to/emacs-mcp/example/install-example.sh
   

4. 测试连接：

   复制

   claude
   # Ask Claude to interact with Emacs
   > Can you list the buffers in my Emacs?
   

框架组件

核心框架文件

• **mcp-server.el**实现MCP协议的TCP服务器（端口8765）
• **mcp-types.el**带有JSON Schema生成和参数验证的类型系统
• **mcp-proxy.sh**使用netcat将标准输入输出桥接到TCP的代理脚本

示例工具

• **examples/mcp-tools.el**包含25+种MCP工具的集合，展示该框架
• **examples/init-example.el**Emacs 配置示例
• **examples/install-example.sh**Claude Code CLI 的安装脚本

示例工具（来自 examples/mcp-tools.el)

缓冲区管理

• **mcp-get-buffer-list**列出所有活动缓冲区，可选详细信息
• **mcp-view-buffer**提取带有行号的缓冲区内容
• **mcp-emacs-buffer-info**包括变量和内容在内的全面缓冲分析
• **mcp-open-file**在 Emacs 中打开文件（带有安全限制）

Emacs 内省（或自我检查/探索）

• **mcp-emacs-search**搜索符号、命令、变量、函数
• **mcp-emacs-describe**获取 Emacs 符号的详细文档
• **mcp-get-variable-value**查询 Emacs 变量值
• **mcp-emacs-keymap-analysis**分析缓冲区键映射和绑定

Org模式集成

• **mcp-get-agenda**导出org-agenda视图
• **mcp-org-agenda-todo-batch**在议程中批量更新待办事项状态
• **mcp-org-schedule-todo**为待办事项安排日期
• **mcp-org-archive-todo**归档已完成的任务
• **mcp-org-capture**通过捕获模板创建新项目
• **mcp-org-get-all-todos**跨文件的全面待办事项列表
• **mcp-org-agenda-goto**根据上下文导航至议程项目来源

工作区管理（Doom Emacs）

• **mcp-get-workspace-buffers**列出工作区中的缓冲区
• **mcp-rename-workspace**为工作区重命名，使用有意义的名称
• **mcp-create-workspace**创建新的项目工作区
• **mcp-delete-workspace**安全删除工作区（保护活跃会话）
• **mcp-move-protected-buffers-to-workspace**在工作区之间移动 Claude/终端会话
• **mcp-setup-workspace-layout**配置窗口布局

Elisp 调试

• **mcp-check-parens**验证Lisp文件中的括号平衡性
• **mcp-count-parens**统计特定行之间的括号数量
• **mcp-check-parens-range**检查行范围内的余额平衡
• **mcp-show-paren-balance**按行显示运行中的余额计数

配置

服务器设置

;; Enable/disable MCP server (default: t)
(setq emacs-mcp-enabled t)

;; TCP port for MCP server (default: 8765)  
(setq emacs-mcp-port 8765)

类型系统设置

;; Enable/disable parameter validation (default: t)
(setq emacs-mcp-enable-validation t)

;; When disabled, all validation is bypassed for performance or debugging
(setq emacs-mcp-enable-validation nil)

安全设置

;; File access restrictions (default: t)
(setq emacs-mcp-restrict-file-access t)

;; Patterns that block buffer access
(setq emacs-mcp-blocked-buffer-patterns
      '("password" ".pem" "secret" ".key" "token" "credential" "auth" ".ssh"))

安全

⚠️ 这个MCP服务器根据您提供的工具，为Claude提供了广泛访问您Emacs环境的权限。示例工具具有以下访问权限：

• 访问可以读取缓冲区、查询变量、访问组织数据
• 限制文件访问仅限于当前目录和 /tmp/ClaudeWorkingFolder/
• 保护输入验证，可配置的缓冲区阻塞模式

克劳德密码特工

这个套餐包括 emacs-manager 由（系统/软件）自动安装的代理 post-build-hook.el （如上文所示的直线安装示例）：

Emacs 管理器专门处理Emacs管理任务的代理，包括括号调试、文件重新加载、配置管理、org-mode交互（待办事项、日程安排、捕获）、Emacs调试（消息缓冲区、缓冲区分析），以及利用所有emacs-mcp.el工具进行全面的Emacs交互。

构建后挂钩会自动从（某个位置）复制代理 agents/emacs-manager.md 到 ~/.claude/agents/ 在软件包安装过程中。

故障排除

• 没有可用工具加载 examples/mcp-tools.el
• 端口冲突改变 emacs-mcp-port
• 调试检查 *Messages* 服务器日志的缓冲区

使用该框架

创建自定义工具

该框架提供了 emacs-mcp-defmcp 用于定义您自己的MCP工具的宏：

(emacs-mcp-defmcp my-custom-tool (name files)
  "Documentation for my custom tool."
  :mcp-description "Brief description for MCP clients"
  :mcp-schema '((name . (string "User name"))
                (files . ((list string) "File paths")))
  ;; Your tool implementation
  (format "Processing %s with %d files" name (length files)))

类型系统

• 基本类型: string， integer， number， boolean， symbol
• 集合: (list type) 对于数组
• 可选： (or type nil) 对于可选参数
• 枚举（Enums）： (choice "option1" "option2") 由于选择有限

示例工具与自定义工具

• 直接使用示例加载 examples/mcp-tools.el 以实现即时功能
• 创建自定义工具使用该框架来构建适用于您工作流程的特定工具
• 将两者混合加载示例，并在旁边添加您自定义的工具

相关项目

• 模型上下文协议
• Claude 命令行接口（CLI）
• claude-code-ide.el（文件名可译为“Claude 代码 IDE 扩展文件”或根据具体上下文调整，但通常文件名直接保留原样） - 为Claude Code集成Emacs IDE，该集成还包含一个MCP服务器——schema格式的灵感来源
• mcp-server-lib.el 翻译为中文是：“MCP 服务器库文件.el”。不过，这里的“.el”通常指的是 Emacs Lisp 的源代码文件扩展名，所以更完整的翻译可能是：“MCP 服务器库的 Emacs Lisp 源代码文件”。但根据上下文和简洁性，通常简化为“MCP 服务器库文件.el”即可 - 另一个Emacs Lisp的MCP服务器实现
• Emacs（一个高度可定制的文本编辑器，常用于编程、写作等）