mcp-server-lib.el

#+TITLE: mcp-server-lib.el - Model Context Protocol Server Library for Emacs Lisp

[[https://github.com/laurynas-biveinis/mcp-server-lib.el/actions/workflows/elisp-test.yml][https://github.com/laurynas-biveinis/mcp-server-lib.el/actions/workflows/elisp-test.yml/badge.svg]] [[https://github.com/laurynas-biveinis/mcp-server-lib.el/actions/workflows/linter.yml][https://github.com/laurynas-biveinis/mcp-server-lib.el/actions/workflows/linter.yml/badge.svg]]

• Overview

=mcp-server-lib.el= is a library for building [[https://modelcontextprotocol.io/][Model Context Protocol]] (MCP) servers in Emacs Lisp. It provides the infrastructure for Emacs packages to expose their functionality as tools and resources to Large Language Models.

• Features

• Simple API for registering tools (Elisp functions) and resources
• Handles MCP protocol communication and JSON-RPC messages
• Stdio transport via emacsclient wrapper script
• Built-in usage metrics and debugging support

• Requirements

• Emacs 27.1 or later
• Running Emacs daemon (for stdio transport)

• MCP servers built on this library

• [[https://github.com/laurynas-biveinis/elisp-dev-mcp][elisp-dev-mcp]] - Elisp development support tools

• Installation

From MELPA:

=M-x package-install RET mcp-server-lib RET=

• For Users

If you're using an MCP server built with this library:

1. Run =M-x mcp-server-lib-install= to install the stdio script
2. The script will be at =~/.emacs.d/emacs-mcp-stdio.sh=
3. Follow your MCP server's documentation for client registration

To uninstall: =M-x mcp-server-lib-uninstall=

• For Developers

To build your own MCP server, see [[https://github.com/laurynas-biveinis/elisp-dev-mcp][elisp-dev-mcp]] for a complete example.

** Client Registration

Register your MCP server with a client using the stdio script:

#+BEGIN_EXAMPLE claude mcp add -s user -t stdio your-server -- ~/.emacs.d/emacs-mcp-stdio.sh
--init-function=your-init-func --stop-function=your-stop-func #+END_EXAMPLE

Script options:

• =--init-function=NAME= - Emacs function to call on startup
• =--stop-function=NAME= - Emacs function to call on shutdown
• =--socket=PATH= - Custom Emacs server socket (optional)

For debugging, set =EMACS_MCP_DEBUG_LOG= to a file path.

** API Reference

*** Registering Tools

#+begin_src elisp (mcp-server-lib-register-tool #'my-function :id "tool-name" :description "What this tool does" :title "Display Name" ; optional :read-only t) ; optional

;; Tool handler with parameters (defun my-handler (location) "Get weather for LOCATION.

MCP Parameters: location - city, address, or coordinates" (mcp-server-lib-with-error-handling ;; Your implementation )) #+end_src

Tool handlers should return strings. Use =mcp-server-lib-tool-throw= for errors or wrap with =mcp-server-lib-with-error-handling=.

Optional properties:

• =:title= - User-friendly display name
• =:read-only= - Set to =t= if tool doesn't modify state

*** Registering Resources

#+begin_src elisp (mcp-server-lib-register-resource "resource://uri" (lambda () "resource content") :name "Resource Name" :description "What this provides" ; optional :mime-type "text/plain") ; optional

;; Dynamic resource example (mcp-server-lib-register-resource "buffer://current" (lambda () (buffer-string)) :name "Current Buffer") #+end_src

Resource handlers take no arguments and return strings. Use regular =error= for failures.

*** Utility Functions

For testing and debugging:

#+begin_src elisp ;; Create JSON-RPC requests (mcp-server-lib-create-tools-list-request &optional id) (mcp-server-lib-create-tools-call-request tool-name &optional id args) (mcp-server-lib-create-resources-list-request &optional id)

;; Process requests and get parsed response (mcp-server-lib-process-jsonrpc-parsed request)

;; Server management (mcp-server-lib-start) (mcp-server-lib-stop) #+end_src

*** Debugging

Enable JSON-RPC message logging:

#+begin_src elisp (setq mcp-server-lib-log-io t) ; Log to mcp-server-lib-log buffer #+end_src

View usage metrics:

#+begin_src elisp M-x mcp-server-lib-show-metrics M-x mcp-server-lib-reset-metrics #+end_src

** Customization

To install the script to a different location:

#+begin_src elisp (setq mcp-server-lib-install-directory "/path/to/directory") #+end_src

• Troubleshooting

• Script not found: Run =M-x mcp-server-lib-install= first
• Connection errors: Ensure Emacs daemon is running
• Debugging: Set =mcp-server-lib-log-io= to =t= and check =mcp-server-lib-log= buffer

• Similar packages

• https://github.com/utsahi/mcp-server.el

• License

This project is licensed under the GNU General Public License v3.0 (GPLv3) - see the LICENSE file for details.

• Acknowledgments

• [[https://modelcontextprotocol.io/][Model Context Protocol]] specification
• [[https://github.com/modelcontextprotocol/python-sdk][Python MCP SDK]] implementation