#+TITLE: MCP.el - Model Context Protocol（模型上下文协议）的 Emacs 客户端

[[https://melpa.org/#/mcp][file:https://melpa.org/packages/mcp-badge.svg]] [[https://www.gnu.org/licenses/gpl-3.0][https://img.shields.io/badge/License-GPLv3-blue.svg]]

这是用于与 [[https://modelcontextprotocol.io/introduction][MCP]] 交互的 Emacs 客户端，支持连接到 MCP 服务器。

• 功能特性

• 与 MCP 服务器的结构化通信
• 支持文件系统和通用 MCP 服务器
• 可扩展的工具和提示系统
• 异步和同步操作
• 资源管理能力
• 直观的服务器生命周期管理接口（启动/停止/重启）
• 与流行 Emacs 插件的集成（如 gptel, llm）

• 安装 需要 Emacs 30 或更高版本

#+begin_src elisp (use-package mcp :ensure t :after gptel :custom (mcp-hub-servers `(("filesystem" . (:command "npx" :args ("-y" "@modelcontextprotocol/server-filesystem") :roots ("/home/lizqwer/MyProject/"))) ("fetch" . (:command "uvx" :args ("mcp-server-fetch"))) ("qdrant" . (:url "http://localhost:8000/sse")) ("graphlit" . ( :command "npx" :args ("-y" "graphlit-mcp-server") :env ( :GRAPHLIT_ORGANIZATION_ID "your-organization-id" :GRAPHLIT_ENVIRONMENT_ID "your-environment-id" :GRAPHLIT_JWT_SECRET "your-jwt-secret"))))) :config (require 'mcp-hub) :hook (after-init . mcp-hub-start-all-server)) #+end_src

• 使用方法 ** Mcp hub *** 配置 MCP 服务器

#+begin_src elisp (setq mcp-hub-servers '(("filesystem" . (:command "npx" :args ("-y" "@modelcontextprotocol/server-filesystem") :roots ("/home/lizqwer/MyProject/"))) ("fetch" . (:command "uvx" :args ("mcp-server-fetch"))) ("qdrant" . (:url "http://localhost:8000/sse")) ("graphlit" . ( :command "npx" :args ("-y" "graphlit-mcp-server") :env ( :GRAPHLIT_ORGANIZATION_ID "your-organization-id" :GRAPHLIT_ENVIRONMENT_ID "your-environment-id" :GRAPHLIT_JWT_SECRET "your-jwt-secret"))))) #+end_src 可以使用 =mcp-hub-start-all-server= 启动所有 MCP 服务器，例如在启动 Emacs 后自动启动所有 MCP 服务器。 #+begin_src elisp (add-hook 'after-init-hook #'mcp-hub-start-all-server) #+end_src *** 管理 MCP 服务器 使用 =mcp-hub= 启动服务器管理界面，该界面会自动启动所有配置的 MCP 服务器。

#+html:

*** 快捷键映射 | 按键 | 函数 | 描述 | |-----+----------------------------+-----------------------------------------| | l | mcp-hub-view-log | 查看服务器日志 | | s | mcp-hub-start-server | 启动光标下的服务器 | | k | mcp-hub-close-server | 停止光标下的服务器 | | r | mcp-hub-restart-server | 重启光标下的服务器 | | S | mcp-hub-start-all-server | 启动所有配置的服务器 | | R | mcp-hub-restart-all-server | 重启所有配置的服务器 | | K | mcp-hub-close-all-server | 停止所有运行的服务器 | | + | mcp-hub-add-root | 向服务器添加根目录 | | - | mcp-hub-remove-root | 从服务器移除根目录 | | = | mcp-hub-view-roots | 查看服务器的根目录 | *** 与 [[https://github.com/karthink/gptel][gptel]] 的集成

• 对于 =gptel= 集成，请参阅 [[https://github.com/karthink/gptel?tab=readme-ov-file#model-context-protocol-mcp-integration][gptel mcp]] 获取详细信息。
• [[https://github.com/lizqwerscott/gptel-mcp.el][gptel-mcp.el]] 是 gptel.el 和 mcp.el 的接口集成 ** 示例 [[https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem][filesystem]] 服务器。 *** 首先建立连接。

#+begin_src elisp (mcp-connect-server "filesystem" :command "npx" :args '("-y" "@modelcontextprotocol/server-filesystem") :roots '("/Downloads/" "/Documents/") :initial-callback #'(lambda (connection) (message "%s connection" (jsonrpc-name connection))) :tools-callback #'(lambda (connection tools) (message "%s tools: %s" (jsonrpc-name connection) tools)) :prompts-callback #'(lambda (connection prompts) (message "%s prompts: %s" (jsonrpc-name connection) prompts)) :resources-callback #'(lambda (connection resources) (message "%s resources: %s" (jsonrpc-name connection) resources))) #+end_src *** 使用文件系统服务器的根目录 文件系统服务器使用 MCP 根目录协议来确定可以访问的目录。可以通过 =:roots= 参数指定目录（而非通过命令行参数传递）：

#+begin_src elisp (mcp-connect-server "filesystem" :command "npx" :args '("-y" "@modelcontextprotocol/server-filesystem") :roots '("/home/user/project1" "/home/user/project2")) #+end_src

连接服务器后也可以动态管理根目录：

#+begin_src elisp ;; 添加新根目录 (mcp-add-root "filesystem" "/home/user/new-project")

;; 移除根目录 (mcp-remove-root "filesystem" "/home/user/old-project")

;; 替换所有根目录 (mcp-set-roots "filesystem" '("/home/user/project1" "/home/user/project2"))

;; 查看当前根目录 (mcp-get-roots "filesystem") #+end_src

Root 指定方式

根目录也可以指定为包含附加元数据的属性列表（plists）:

  (mcp-connect-server "filesystem"
                      :command "npx"
                      :args '("-y" "@modelcontextprotocol/server-filesystem")
                      :roots '((:uri "file:///home/user/project" :name "My Project")
                               "/home/user/downloads"))

定义工具使用方式

当前文本正在使用 [[https://github.com/karthink/gptel/issues/514][gptel tool]] 分支进行测试。使用 mcp-make-text-tool 创建标准工具调用数据（[[https://github.com/ahyatt/llm/discussions/124][Discussions]]）。建议在 tools-callback 内创建工具，或等待 mcp 连接服务器完成。

  (mcp-make-text-tool "filesystem" "write_file")

这将生成一个数据结构，其中函数是用于访问 MCP 服务器的自动生成的同步或异步 lambda 函数。

  (list :function #'(lambda (&rest args)
                      ;; Synchronous or asynchronous access to the MCP server's Lambda function.
                      )
        :name "write_file"
        :async nil
        :description "Create a new file or completely overwrite an existing file with new content. Use with caution as it will overwrite existing files without warning. Handles text content with proper encoding. Only works within allowed directories."
        :args ((:type "string" :name "path" :description "path")
               (:type "string" :name "content" :description "content"))
        :category "files")

与服务器断开连接

  (mcp-stop-server "filesystem")

手动函数调用

同步调用

  (let ((connection (gethash "filesystem" mcp-server-connections)))
    (mcp-call-tool connection "write_file" '(:path "filename or file path" :content "the file content")))

异步调用

  (let ((connection (gethash "filesystem" mcp-server-connections)))
    (mcp-async-call-tool connection
                         "write_file"
                         '(:path "filename or file path" :content "the file content")
                         #'(lambda (res)
                             ;; handle res
                             (mcp--parse-tool-call-result res))
                         #'(lambda (code message)
                             ;; handle error
                             (format "call %s tool error with %s: %s"
                                     tool-name
                                     code
                                     message))))

手动获取提示

由于 [[https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem][filesystem]] 服务器缺少提示功能，此处使用 [[https://github.com/modelcontextprotocol/servers/tree/main/src/everything][everything]] 服务器进行演示。

同步调用

  (let ((connection (gethash "everything" mcp-server-connections)))
    (mcp-get-prompt connection "complex_prompt" '(:temperature "1.0")))

异步调用

  (let ((connection (gethash "everything" mcp-server-connections)))
    (mcp-async-get-prompt connection
                          "complex_prompt"
                          '(:temperature "1.0")
                          #'(lambda (res)
                              (message "prompt: %s" res))
                          #'(lambda (code message)
                              (message "error call: %s, %s" code message))))

手动获取资源

由于 [[https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem][filesystem]] 服务器缺少资源功能，此处使用 [[https://github.com/modelcontextprotocol/servers/tree/main/src/everything][everything]] 服务器进行演示。

同步调用

  (let ((connection (gethash "everything" mcp-server-connections)))
    (mcp-read-resource connection "test://static/resource/1"))

异步调用

  (let ((connection (gethash "everything" mcp-server-connections)))
    (mcp-async-read-resource connection "test://static/resource/1"
                             #'(lambda (resource)
                                 (message "res: %s" resource))))

获取资源模板

由于 [[https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem][filesystem]] 服务器缺少资源功能，此处使用 [[https://github.com/modelcontextprotocol/servers/tree/main/src/everything][everything]] 服务器进行演示。

  (let ((connection (gethash "everything" mcp-server-connections)))
    (mcp-async-list-resource-templates connection
                                       #'(lambda (connection templates)
                                           (message "%s" templates))))

开发路线图

• 基于 HTTP SSE 的 MCP 服务器连接
• MCP 市场（浏览器和自动安装 MCP 服务器）
• 与其他 Emacs AI 客户端的简化集成
• 扩展文档
• 完整的 MCP 协议客户端实现

许可证

本项目采用 GNU General Public License v3.0 许可证 - 详见 [[file:LICENSE][LICENSE]] 文件。

mcp.el 快速上手指南

环境准备

• 系统要求：Emacs 30 或更高版本
• 前置依赖：
  • Node.js（用于 npx 命令）
  • uvx 工具（用于 mcp-server-fetch 服务）

安装步骤

1. 添加 MELPA 源（如未配置）：

   (require 'package)
   (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
   (package-refresh-contents)
   

2. 安装 mcp 包：

   (use-package mcp
     :ensure t
     :after gptel
     :custom (mcp-hub-servers
              '((:name "filesystem"
                       :command "npx"
                       :args ("-y" "@modelcontextprotocol/server-filesystem")
                       :roots ("/home/yourname/Projects/"))))
     :config (require 'mcp-hub)
     :hook (after-init . mcp-hub-start-all-server))
   

基本使用

启动 MCP 服务

1. 配置服务器（以文件系统服务为例）：

   (setq mcp-hub-servers
         '((:name "filesystem"
                  :command "npx"
                  :args ("-y" "@modelcontextprotocol/server-filesystem")
                  :roots ("/home/yourname/Projects/"))))
   

2. 自动启动服务（Emacs 启动时）：

   (add-hook 'after-init-hook #'mcp-hub-start-all-server)
   

快速操作示例

1. 启动服务：
   执行 M-x mcp-hub，按 S 键启动所有服务。

2. 调用工具（以文件写入为例）：

   (let ((conn (gethash "filesystem" mcp-server-connections)))
     (mcp-call-tool conn "write_file"
                    '(:path "test.txt" :content "Hello, MCP!")))
   

3. 管理根目录：

   ;; 添加目录
   (mcp-add-root "filesystem" "/home/yourname/NewProject")
   ;; 查看当前目录
   (mcp-get-roots "filesystem")
   

快捷键速查

操作	快捷键	功能描述
启动服务	s	启动当前选中服务
停止服务	k	停止当前选中服务
查看日志	l	显示服务日志
添加根目录	+	动态扩展服务访问路径

提示：首次使用建议从 filesystem 服务开始，确保 Node.js 环境已安装。