Content
#+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]]
[[https://melpa.org/#/mcp-server-lib][https://melpa.org/packages/mcp-server-lib-badge.svg]]
[[https://stable.melpa.org/#/mcp-server-lib][file:https://stable.melpa.org/packages/mcp-server-lib-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
- Multi-server support
- Resource templates with URI pattern matching (RFC 6570 subset)
- 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
- [[https://github.com/laurynas-biveinis/org-mcp][org-mcp]] - read and write Org content
* Installation
From [[https://melpa.org/#/mcp-server-lib][MELPA]] or [[https://stable.melpa.org/#/mcp-server-lib][MELPA Stable]]:
=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
Available commands:
- =M-x mcp-server-lib-start= - Start the MCP server
- =M-x mcp-server-lib-stop= - Stop the MCP server
- =M-x mcp-server-lib-describe-setup= - View registered tools and resources with usage statistics
- =M-x mcp-server-lib-show-metrics= - View usage metrics
- =M-x mcp-server-lib-uninstall= - Remove the stdio script
* 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)
- =--server-id=ID= - Explicit server identifier (optional, will become mandatory in
the future)
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
:server-id "my-server") ; optional
;; Tool handler with one parameter
(defun my-handler (location)
"Get weather for LOCATION.
MCP Parameters:
location - city, address, or coordinates"
(mcp-server-lib-with-error-handling
;; Your implementation
))
;; Tool handler with multiple parameters
(defun update-todo-state (resource-uri current-state new-state)
"Update TODO state of a task.
MCP Parameters:
resource-uri - URI of the task to update
current-state - Current TODO state (or empty string)
new-state - New TODO state to set"
(mcp-server-lib-with-error-handling
;; Direct access to parameters, no alist-get needed
(message "Updating %s from %s to %s"
resource-uri current-state new-state)))
(mcp-server-lib-register-tool #'update-todo-state
:id "update-todo"
:description "Update task TODO state"
:server-id "my-server") ; optional
#+end_src
**** MCP Parameters Format
Parameter descriptions in tool handler docstrings follow an indentation-based format:
- Parameter definitions use 2-4 spaces: ~ param-name - description~
- Continuation lines use 6+ spaces: ~ additional text~
- Continuation lines can span multiple lines
- All function parameters must be documented
Example with multi-line parameter descriptions:
#+begin_src elisp
(defun fetch-content (url timeout)
"Fetch content from a URL.
MCP Parameters:
url - web address to fetch
Supports http, https, and file protocols
Must be a valid URI
timeout - seconds to wait before giving up
Use 0 for no timeout"
(mcp-server-lib-with-error-handling
;; Implementation
))
#+end_src
Tools can have zero, one, or multiple parameters. When a tool has multiple
parameters, the JSON object fields from the client are automatically mapped to the
function parameters by name (converting from camelCase to kebab-case as needed).
Tools do not support =&rest= parameters.
Tool handlers must return strings or =nil= (which is converted to an empty string).
Other return types will cause an "Invalid Params" error.
If a tool cannot complete its operation successfully, it should use
=mcp-server-lib-tool-throw= for throwing an error or the implementation should be
wrapped 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
- =:server-id= - Server identifier (optional, defaults to ="default"=)
*** Registering Resources
The library uses a unified API for both static and templated resources. The presence of ={variable}= syntax automatically determines whether a resource is static or templated:
#+begin_src elisp
;; Static resource (no variables)
(mcp-server-lib-register-resource "resource://uri"
(lambda () "resource content")
:name "Resource Name"
:description "What this provides" ; optional
:mime-type "text/plain" ; optional
:server-id "my-server") ; optional
;; Dynamic resource example
(mcp-server-lib-register-resource "buffer://current"
(lambda () (buffer-string))
:name "Current Buffer"
:server-id "my-server") ; optional
;; Template resource with simple variable
(mcp-server-lib-register-resource "org://{filename}"
(lambda (params)
(with-temp-buffer
(insert-file-contents (alist-get "filename" params nil nil #'string=))
(buffer-string)))
:name "Org file content"
:description "Read any org file by name"
:server-id "my-server") ; optional
;; Template with multiple variables
(mcp-server-lib-register-resource "org://{filename}/headline/{+path}"
(lambda (params)
(let ((file (alist-get "filename" params nil nil #'string=))
(path (alist-get "path" params nil nil #'string=)))
;; path can contain slashes with {+path}
(org-get-headline-content file path)))
:name "Org headline"
:description "Get specific headline from org file"
:server-id "my-server") ; optional
#+end_src
Static resource handlers take no arguments and return strings. Template resource handlers receive an alist of parameters extracted from the URI.
Supported template syntax (RFC 6570 subset):
- ={variable}= - Simple variable expansion
- ={+variable}= - Reserved expansion (allows slashes)
Direct resources take precedence over templates when both match a URI.
*** Resource Error Handling
Resource handlers can signal specific JSON-RPC error codes to provide meaningful error information to clients:
#+begin_src elisp
;; Signal that client provided invalid parameters
(defun my-file-resource-handler (params)
(let ((file (alist-get "filename" params nil nil #'string=)))
(unless (file-exists-p file)
(mcp-server-lib-resource-signal-error
mcp-server-lib-jsonrpc-error-invalid-params
(format "File not found: %s" file)))
(with-temp-buffer
(insert-file-contents file)
(buffer-string))))
;; Signal an internal server error
(defun my-database-resource-handler ()
(unless (database-connected-p)
(mcp-server-lib-resource-signal-error
mcp-server-lib-jsonrpc-error-internal
"Database connection unavailable"))
(query-database))
#+end_src
Available error codes:
- =mcp-server-lib-jsonrpc-error-invalid-params= (-32602): Client provided invalid parameters, resource not found
- =mcp-server-lib-jsonrpc-error-internal= (-32603): Server-side processing error
It is also possible to use regular =error= or =signal= calls, which would return internal error (-32603).
*** Working with Resource Templates
Resource template handlers receive extracted parameters as an alist. These parameters are matched from the URI but not automatically decoded - if you're working with file paths that might contain special characters, you'll want to decode them:
#+begin_src elisp
(mcp-server-lib-register-resource "file://{path}"
(lambda (params)
(let ((path (alist-get "path" params nil nil #'string=)))
;; Decode if needed for filesystem access
(with-temp-buffer
(insert-file-contents (url-unhex-string path))
(buffer-string))))
:name "File reader"
:server-id "my-server") ; optional
#+end_src
Variable names in templates follow simple rules - stick to letters, numbers, and underscores. The URI scheme (like =file://= or =org://=) needs to be a valid URI scheme starting with a letter. URI schemes are case-insensitive per RFC 3986, so =HTTP://example.com= will match a template registered as =http://{domain}=.
When multiple templates could match the same URI, which template is selected is undefined and depends on implementation details. Avoid registering overlapping templates.
Templates can match empty values too - =org://= will match =org://{filename}= with an empty filename.
Literal segments in templates must match exactly - =test://items/{id}= will match =test://items/123= but not =test://item/123=.
The implementation uses non-greedy (first-match) behavior when matching variables. For example, =test://{name}.txt= matching =test://file.config.txt= extracts =name="file.config"=, not =name="file.config.txt"=.
To unregister any resource (static or templated):
#+begin_src elisp
(mcp-server-lib-unregister-resource "org://{filename}" :server-id "my-server")
(mcp-server-lib-unregister-resource "resource://uri" :server-id "my-server")
#+end_src
*** Resource Lists
When clients request the resource list, direct resources appear with a =uri= field while templates show up with a =uriTemplate= field. This helps clients distinguish between static resources and dynamic patterns they can use.
*** Constants
=mcp-server-lib-name= - The name of the MCP server ("emacs-mcp-server-lib")
=mcp-server-lib-protocol-version= - The MCP protocol version supported by this server ("2025-03-26")
*** 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)
(mcp-server-lib-create-resources-read-request uri &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
*** Test Utilities
The =mcp-server-lib-ert= module provides utilities for writing ERT tests for MCP servers:
**** Server Context Variable
Test helper functions use the dynamic variable =mcp-server-lib-ert-server-id= to determine which server to operate on. Child packages testing a single server should set this once at the top of their test file:
#+begin_src elisp
;; At the top of your test file
(setq mcp-server-lib-ert-server-id "my-mcp-server")
#+end_src
**** Test Helper Functions
#+begin_src elisp
;; Track metrics changes during test execution
(mcp-server-lib-ert-with-metrics-tracking
((method expected-calls expected-errors) ...)
;; Test code here
)
;; Example: Verify a method is called once with no errors
(mcp-server-lib-ert-with-metrics-tracking
(("tools/list" 1 0))
;; Code that should call tools/list once
(mcp-server-lib-process-jsonrpc-parsed
(mcp-server-lib-create-tools-list-request)))
;; Simplified syntax for verifying successful single method calls
(mcp-server-lib-ert-verify-req-success "tools/list"
(mcp-server-lib-process-jsonrpc-parsed
(mcp-server-lib-create-tools-list-request)))
;; Process a request and get the successful result
(let* ((request (mcp-server-lib-create-tools-list-request))
(tools (mcp-server-lib-ert-get-success-result "tools/list" request)))
;; tools contains the result field from the response
(should (arrayp tools)))
;; High-level tool testing helper - simplifies tool calls
;; This function combines request creation, processing, metrics verification,
;; and text extraction into a single call
(let* ((params '(("name" . "John") ("greeting" . "Hello")))
(result (mcp-server-lib-ert-call-tool "greet-user" params)))
(should (string= "Hello, John!" result)))
;; Get resource list (convenience function)
(let ((resources (mcp-server-lib-ert-get-resource-list)))
(should (= 2 (length resources)))
(should (string= "test://resource1"
(alist-get 'uri (aref resources 0)))))
;; Check error response structure
(mcp-server-lib-ert-check-error-object response -32601 "Method not found")
;; Verify resource read succeeds with expected fields
(mcp-server-lib-ert-verify-resource-read
"test://resource1"
'((uri . "test://resource1")
(mimeType . "text/plain")
(text . "test result")))
;; Run tests with MCP server
(mcp-server-lib-ert-with-server :tools nil :resources nil
;; Server is started, initialized, and will be stopped after body
(let ((response (mcp-server-lib-process-jsonrpc-parsed
(json-encode '(("jsonrpc" . "2.0")
("method" . "tools/list")
("id" . 1))))))
(should-not (alist-get 'error response))))
#+end_src
*** JSON-RPC Error Constants
The library provides public constants for standard JSON-RPC 2.0 error codes:
#+begin_src elisp
mcp-server-lib-jsonrpc-error-parse ; -32700 Parse Error
mcp-server-lib-jsonrpc-error-invalid-request ; -32600 Invalid Request
mcp-server-lib-jsonrpc-error-method-not-found ; -32601 Method Not Found
mcp-server-lib-jsonrpc-error-invalid-params ; -32602 Invalid Params
mcp-server-lib-jsonrpc-error-internal ; -32603 Internal Error
#+end_src
These constants can be used when checking error responses in tests:
#+begin_src elisp
(mcp-server-lib-ert-check-error-object
response
mcp-server-lib-jsonrpc-error-method-not-found
"Method not found")
#+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
- https://github.com/rhblind/emacs-mcp-server
* 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
