Skip to content
Back to search

mcp.el

An Mcp client inside Emacs

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lizqwerscott--mcp-el/badge.svg)](/listings/lizqwerscott--mcp-el)

HTML

<a href="/listings/lizqwerscott--mcp-el"><img src="/api/listings/lizqwerscott--mcp-el/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

Readme.org · README · 227 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. #+TITLE: MCP.el - Model Context Protocol for Emacs
  2. [[https://melpa.org/#/mcp][file:https://melpa.org/packages/mcp-badge.svg]]
  3. [[https://www.gnu.org/licenses/gpl-3.0][https://img.shields.io/badge/License-GPLv3-blue.svg]]
  4. This is an Emacs client for interfacing with [[https://modelcontextprotocol.io/introduction][MCP]], supporting connections to MCP servers.
  5. * Features
  6. - Structured communication with MCP servers
  7. - Support for filesystem and generic MCP servers
  8. - Extensible tool and prompt system
  9. - Asynchronous and synchronous operations
  10. - Resource management capabilities
  11. - Intuitive interface for managing server lifecycle (start/stop/restart)
  12. - Integration with popular Emacs packages (e.g., gptel, llm)
  13. * Installation
  14. Need Emacs 30 or higher version
  15. #+begin_src elisp
  16. (use-package mcp
  17. :ensure t
  18. :after gptel
  19. :custom (mcp-hub-servers
  20. `(("filesystem" . (:command "npx"
  21. :args ("-y" "@modelcontextprotocol/server-filesystem")
  22. :roots ("/home/lizqwer/MyProject/")))
  23. ("fetch" . (:command "uvx" :args ("mcp-server-fetch")))
  24. ("qdrant" . (:url "http://localhost:8000/sse"))
  25. ("graphlit" . (
  26. :command "npx"
  27. :args ("-y" "graphlit-mcp-server")
  28. :env (
  29. :GRAPHLIT_ORGANIZATION_ID "your-organization-id"
  30. :GRAPHLIT_ENVIRONMENT_ID "your-environment-id"
  31. :GRAPHLIT_JWT_SECRET "your-jwt-secret")))))
  32. :config (require 'mcp-hub)
  33. :hook (after-init . mcp-hub-start-all-server))
  34. #+end_src
  35. * Usage
  36. ** Mcp hub
  37. *** Configuring MCP Servers
  38. #+begin_src elisp
  39. (setq mcp-hub-servers
  40. '(("filesystem" . (:command "npx"
  41. :args ("-y" "@modelcontextprotocol/server-filesystem")
  42. :roots ("/home/lizqwer/MyProject/")))
  43. ("fetch" . (:command "uvx" :args ("mcp-server-fetch")))
  44. ("qdrant" . (:url "http://localhost:8000/sse"))
  45. ("graphlit" . (
  46. :command "npx"
  47. :args ("-y" "graphlit-mcp-server")
  48. :env (
  49. :GRAPHLIT_ORGANIZATION_ID "your-organization-id"
  50. :GRAPHLIT_ENVIRONMENT_ID "your-environment-id"
  51. :GRAPHLIT_JWT_SECRET "your-jwt-secret")))))
  52. #+end_src
  53. You can use =mcp-hub-start-all-server= to start all MCP servers, such as launching all MCP servers after starting Emacs.
  54. #+begin_src elisp
  55. (add-hook 'after-init-hook
  56. #'mcp-hub-start-all-server)
  57. #+end_src
  58. *** Managing MCP Servers
  59. Use =mcp-hub= to launch the server management interface, which will automatically start all configured MCP servers.
  60. #+html: <img src="https://github.com/user-attachments/assets/31877c0b-d71a-491d-9830-2afed8d6218a" alt="mcp-hub"/>
  61. *** Keymap
  62. | key | function | description |
  63. |-----+----------------------------+-----------------------------------------|
  64. | l | mcp-hub-view-log | View server logs |
  65. | s | mcp-hub-start-server | Start server under cursor |
  66. | k | mcp-hub-close-server | Stop server under cursor |
  67. | r | mcp-hub-restart-server | Restart server under cursor |
  68. | S | mcp-hub-start-all-server | Start all configured servers |
  69. | R | mcp-hub-restart-all-server | Restart all configured servers |
  70. | K | mcp-hub-close-all-server | Stop all running servers |
  71. | + | mcp-hub-add-root | Add root directory to server |
  72. | - | mcp-hub-remove-root | Remove root directory from server |
  73. | = | mcp-hub-view-roots | View server's root directories |
  74. *** use with [[https://github.com/karthink/gptel][gptel]]
  75. - For =gptel= integration, See the [[https://github.com/karthink/gptel?tab=readme-ov-file#model-context-protocol-mcp-integration][gptel mcp]] for details.
  76. - [[https://github.com/lizqwerscott/gptel-mcp.el][gptel-mcp.el]] is interface integration for gptel.el and mcp.el
  77. ** Example [[https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem][filesystem]] server.
  78. *** Establish the connection first.
  79. #+begin_src elisp
  80. (mcp-connect-server "filesystem"
  81. :command "npx"
  82. :args '("-y" "@modelcontextprotocol/server-filesystem")
  83. :roots '("~/Downloads/" "~/Documents/")
  84. :initial-callback
  85. #'(lambda (connection)
  86. (message "%s connection" (jsonrpc-name connection)))
  87. :tools-callback
  88. #'(lambda (connection tools)
  89. (message "%s tools: %s" (jsonrpc-name connection) tools))
  90. :prompts-callback
  91. #'(lambda (connection prompts)
  92. (message "%s prompts: %s" (jsonrpc-name connection) prompts))
  93. :resources-callback
  94. #'(lambda (connection resources)
  95. (message "%s resources: %s" (jsonrpc-name connection) resources)))
  96. #+end_src
  97. *** Using Roots with Filesystem Server
  98. The filesystem server uses the MCP roots protocol to determine which directories it can access. Instead of passing directories as command-line arguments, you can specify them using the =:roots= parameter:
  99. #+begin_src elisp
  100. (mcp-connect-server "filesystem"
  101. :command "npx"
  102. :args '("-y" "@modelcontextprotocol/server-filesystem")
  103. :roots '("/home/user/project1" "/home/user/project2"))
  104. #+end_src
  105. You can also dynamically manage roots after the server is connected:
  106. #+begin_src elisp
  107. ;; Add a new root directory
  108. (mcp-add-root "filesystem" "/home/user/new-project")
  109. ;; Remove a root directory
  110. (mcp-remove-root "filesystem" "/home/user/old-project")
  111. ;; Replace all roots
  112. (mcp-set-roots "filesystem" '("/home/user/project1" "/home/user/project2"))
  113. ;; View current roots
  114. (mcp-get-roots "filesystem")
  115. #+end_src
  116. Roots can also be specified as plists with additional metadata:
  117. #+begin_src elisp
  118. (mcp-connect-server "filesystem"
  119. :command "npx"
  120. :args '("-y" "@modelcontextprotocol/server-filesystem")
  121. :roots '((:uri "file:///home/user/project" :name "My Project")
  122. "/home/user/downloads"))
  123. #+end_src
  124. *** Define the use of tools.
  125. The current text is being tested using the [[https://github.com/karthink/gptel/issues/514][gptel tool]] branch.Use =mcp-make-text-tool= to create standard tool call data ([[https://github.com/ahyatt/llm/discussions/124][Discussions]]).It is recommended to create tools within the tools-callback or wait for the mcp connect server to complete.
  126. #+begin_src elisp
  127. (mcp-make-text-tool "filesystem" "write_file")
  128. #+end_src
  129. This will generate a data structure where the function is an auto-generated synchronous or asynchronous lambda function for accessing the MCP server.
  130. #+begin_src elisp
  131. (list :function #'(lambda (&rest args)
  132. ;; Synchronous or asynchronous access to the MCP server's Lambda function.
  133. )
  134. :name "write_file"
  135. :async nil
  136. :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."
  137. :args ((:type "string" :name "path" :description "path")
  138. (:type "string" :name "content" :description "content"))
  139. :category "files")
  140. #+end_src
  141. *** Disconnect from the server.
  142. #+begin_src elisp
  143. (mcp-stop-server "filesystem")
  144. #+end_src
  145. *** Manual function call
  146. **** Synchronize
  147. #+begin_src elisp
  148. (let ((connection (gethash "filesystem" mcp-server-connections)))
  149. (mcp-call-tool connection "write_file" '(:path "filename or file path" :content "the file content")))
  150. #+end_src
  151. **** Asynchronous
  152. #+begin_src elisp
  153. (let ((connection (gethash "filesystem" mcp-server-connections)))
  154. (mcp-async-call-tool connection
  155. "write_file"
  156. '(:path "filename or file path" :content "the file content")
  157. #'(lambda (res)
  158. ;; handle res
  159. (mcp--parse-tool-call-result res))
  160. #'(lambda (code message)
  161. ;; handle error
  162. (format "call %s tool error with %s: %s"
  163. tool-name
  164. code
  165. message))))
  166. #+end_src
  167. *** Manual get prompt
  168. Since the [[https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem][filesystem]] lacks prompts, the [[https://github.com/modelcontextprotocol/servers/tree/main/src/everything][everything]] server is used for demonstration.
  169. **** Synchronize
  170. #+begin_src elisp
  171. (let ((connection (gethash "everything" mcp-server-connections)))
  172. (mcp-get-prompt connection "complex_prompt" '(:temperature "1.0")))
  173. #+end_src
  174. **** Asynchronous
  175. #+begin_src elisp
  176. (let ((connection (gethash "everything" mcp-server-connections)))
  177. (mcp-async-get-prompt connection
  178. "complex_prompt"
  179. '(:temperature "1.0")
  180. #'(lambda (res)
  181. (message "prompt: %s" res))
  182. #'(lambda (code message)
  183. (message "error call: %s, %s" code message))))
  184. #+end_src
  185. *** Manual get resources
  186. Since the [[https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem][filesystem]] lacks resources, the [[https://github.com/modelcontextprotocol/servers/tree/main/src/everything][everything]] server is used for demonstration.
  187. **** Synchronize
  188. #+begin_src elisp
  189. (let ((connection (gethash "everything" mcp-server-connections)))
  190. (mcp-read-resource connection "test://static/resource/1"))
  191. #+end_src
  192. **** Asynchronous
  193. #+begin_src elisp
  194. (let ((connection (gethash "everything" mcp-server-connections)))
  195. (mcp-async-read-resource connection "test://static/resource/1"
  196. #'(lambda (resource)
  197. (message "res: %s" resource))))
  198. #+end_src
  199. *** Get resource templates
  200. Since the [[https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem][filesystem]] lacks resources, the [[https://github.com/modelcontextprotocol/servers/tree/main/src/everything][everything]] server is used for demonstration.
  201. #+begin_src elisp
  202. (let ((connection (gethash "everything" mcp-server-connections)))
  203. (mcp-async-list-resource-templates connection
  204. #'(lambda (connection templates)
  205. (message "%s" templates))))
  206. #+end_src
  207. * Roadmap
  208. - [X] HTTP SSE based MCP server connections
  209. - [ ] mcp marketplace (browser and auto install mcp server)
  210. - [ ] Simplified integration with other Emacs AI clients
  211. - [ ] Expanded documentation
  212. - [ ] Full MCP protocol client implementation
  213. * License
  214. This project is licensed under the GNU General Public License v3.0 - see the [[file:LICENSE][LICENSE]] file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.