A Clojure SDK to create MCP servers (and eventually clients)
A clojure-sdk
for creating Model Context Protocol servers!
The calculator_server.clj file and vegalite_server.clj file examples contains a full working code for defining an MCP server.
examples
is a deps-new
app project, and instructions for compiling
and running the various example servers are in the examples/README.md
file (also copied below this section)
The deps for clojure-sdk
are:
{io.modelcontextprotocol/mcp-clojure-sdk
{:git/url "https://github.com/unravel-team/mcp-clojure-sdk.git"
:git/sha "039cf220ac6bb3858f71e823016035e257a5380d"}}
For your ease of use, there is also a deps-new
template and a Github template. See:
deps-new
based template to quickly create new MCP servers.$ make clean && make examples-jar
The examples jar contains the following servers:
calculator_server
vegalite_server
code_analysis_server
calculator_server
Provides basic arithmetic tools: add
, subtract
, multiply
,
divide
, power
, square-root
, average
, factorial
Some example commands you can try in Claude Desktop or Inspector:
Remember:
"calculator": {
"command": "java",
"args": [
"-Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory",
"-Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog",
"-Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector",
"-Dlog4j2.configurationFile=log4j2-mcp.xml",
"-Dbabashka.json.provider=metosin/jsonista",
"-Dlogging.level=INFO",
"-cp",
"/Users/vedang/mcp-clojure-sdk/examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar",
"calculator_server"
]
}
npx @modelcontextprotocol/inspector java -Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog -Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector -Dlog4j2.configurationFile=log4j2-mcp.xml -Dbabashka.json.provider=metosin/jsonista -Dlogging.level=INFO -cp examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar calculator_server
vegalite_server
Provides tools for generating Vega-lite charts: save-data
,
visualize-data
.
PRE-REQUISITES: Needs vl-convert CLI to be installed.
Some example commands you can try in Claude Desktop or Inspector:
Here is some example data for you:
[
{ "year": 2011, "value": 14.6, "growth_type": "Market Cap Growth" },
{ "year": 2011, "value": 11.4, "growth_type": "Revenue Growth" },
{ "year": 2011, "value": 26.6, "growth_type": "Net Income Growth" },
{ "year": 2012, "value": 40.1, "growth_type": "Market Cap Growth" },
{ "year": 2012, "value": 42.7, "growth_type": "Revenue Growth" },
{ "year": 2012, "value": 36.9, "growth_type": "Net Income Growth" },
{ "year": 2013, "value": 16.9, "growth_type": "Market Cap Growth" },
{ "year": 2013, "value": 14.6, "growth_type": "Revenue Growth" },
{ "year": 2013, "value": 15.3, "growth_type": "Net Income Growth" },
{ "year": 2014, "value": 9.6, "growth_type": "Market Cap Growth" },
{ "year": 2014, "value": 7.9, "growth_type": "Revenue Growth" },
{ "year": 2014, "value": 10.9, "growth_type": "Net Income Growth" },
{ "year": 2015, "value": 5.8, "growth_type": "Market Cap Growth" },
{ "year": 2015, "value": 6.7, "growth_type": "Revenue Growth" },
{ "year": 2015, "value": 6.2, "growth_type": "Net Income Growth" },
{ "year": 2016, "value": -12.4, "growth_type": "Market Cap Growth" },
{ "year": 2016, "value": -3.9, "growth_type": "Revenue Growth" },
{ "year": 2016, "value": -32.2, "growth_type": "Net Income Growth" },
{ "year": 2017, "value": 25.3, "growth_type": "Market Cap Growth" },
{ "year": 2017, "value": 5.9, "growth_type": "Revenue Growth" },
{ "year": 2017, "value": 43.9, "growth_type": "Net Income Growth" }
]
Visualize this data for me using vega-lite.
Remember:
vl-convert
on your system "vegalite": {
"command": "java",
"args": [
"-Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory",
"-Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog",
"-Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector",
"-Dlog4j2.configurationFile=log4j2-mcp.xml",
"-Dbabashka.json.provider=metosin/jsonista",
"-Dlogging.level=INFO",
"-Dmcp.vegalite.vl_convert_executable=/Users/vedang/.cargo/bin/vl-convert",
"-cp",
"/Users/vedang/mcp-clojure-sdk/examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar",
"vegalite_server"
]
}
Remember to use the full-path to the examples JAR on your system, or
execute this command from the mcp-clojure-sdk
repo.
npx @modelcontextprotocol/inspector java -Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog -Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector -Dlog4j2.configurationFile=log4j2-mcp.xml -Dbabashka.json.provider=metosin/jsonista -Dlogging.level=INFO -Dmcp.vegalite.vl_convert_executable=/Users/vedang/.cargo/bin/vl-convert -cp examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar vegalite_server
code_analysis_server
This server is an example of a server which provides prompts and not
tools. The following prompts are available: analyse-code
and
poem-about-code
.
You can try the prompts out in Claude Desktop or Inspector. While these prompts are very basic, this is a good way to see how you could expose powerful prompts through this technique.
Remember:
"code-anaylsis": {
"command": "java",
"args": [
"-Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory",
"-Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog",
"-Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector",
"-Dlog4j2.configurationFile=log4j2-mcp.xml",
"-Dbabashka.json.provider=metosin/jsonista",
"-Dlogging.level=INFO",
"-cp",
"/Users/vedang/mcp-clojure-sdk/examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar",
"code_analysis_server"
]
}
(Remember to use the full-path to the examples JAR on your system, or
execute this command from the mcp-clojure-sdk
repo)
npx @modelcontextprotocol/inspector java -Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog -Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector -Dlog4j2.configurationFile=log4j2-mcp.xml -Dbabashka.json.provider=metosin/jsonista -Dlogging.level=INFO -cp examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar code_analysis_server
Server Implementation: The core server functionality is
implemented in server.clj
, which handles request/response cycles
for various MCP methods.
Transport Layer: The SDK implements a STDIO transport in
stdio_server.clj
using io_chan.clj
to convert between IO
streams and core.async channels.
Error Handling: Custom error handling is defined in
mcp/errors.clj
.
Protocol Specifications: All protocol specifications are
defined in specs.clj
, which provides validation for requests,
responses, and server components.
The sequence diagram shows the typical lifecycle of an MCP client-server interaction:
Initialization Phase:
initialize
requestinitialized
notificationDiscovery Phase:
tools/list
, resources/list
and prompts/list
Tool Interaction:
Resource Interaction:
Prompt Interaction:
Optional Features:
sequenceDiagram
participant Client
participant MCPServer
participant Tool
participant Resource
participant Prompt
Note over Client,MCPServer: Initialization Phase
Client->>+MCPServer: initialize
MCPServer-->>-Client: initialize response (capabilities)
Client->>MCPServer: notifications/initialized
Note over Client,MCPServer: Discovery Phase
Client->>+MCPServer: tools/list
MCPServer-->>-Client: List of available tools
Client->>+MCPServer: resources/list
MCPServer-->>-Client: List of available resources
Client->>+MCPServer: prompts/list
MCPServer-->>-Client: List of available prompts
Note over Client,MCPServer: Tool Interaction
Client->>+MCPServer: tools/call (name, arguments)
MCPServer->>+Tool: handler(arguments)
Tool-->>-MCPServer: result
MCPServer-->>-Client: Tool response
Note over Client,MCPServer: Resource Interaction
Client->>+MCPServer: resources/read (uri)
MCPServer->>+Resource: handler(uri)
Resource-->>-MCPServer: contents
MCPServer-->>-Client: Resource contents
Note over Client,MCPServer: Prompt Interaction
Client->>+MCPServer: prompts/get (name, arguments)
MCPServer->>+Prompt: handler(arguments)
Prompt-->>-MCPServer: messages
MCPServer-->>-Client: Prompt messages
Note over Client,MCPServer: Optional Subscription
Client->>+MCPServer: resources/subscribe (uri)
MCPServer-->>-Client: Empty response
MCPServer-->>Client: notifications/resources/updated
Note over Client,MCPServer: Health Check
Client->>+MCPServer: ping
MCPServer-->>-Client: pong
You can help dear reader! Head over to the todo.org file to see the list of pending changes, arranged roughly in the order I plan to tackle them.
The clojure-sdk
is a standard deps-new
project, so you should
expect all the deps-new
commands to work as expected. Even so:
Run the project's tests:
$ make test ## or clojure -T:build test
Run the project's CI pipeline and build a JAR:
$ make build ## or clojure -T:build ci
This will produce an updated pom.xml
file with synchronized
dependencies inside the META-INF
directory inside target/classes
and the JAR in target
. You can update the version (and SCM tag)
information in generated pom.xml
by updating build.clj
.
Install it locally:
$ make install ## or clojure -T:build install
Deploy it to Clojars -- needs CLOJARS_USERNAME
and
CLOJARS_PASSWORD
environment variables (requires the ci
task be
run first):
$ make deploy ## or clojure -T:build deploy
Your library will be deployed to io.modelcontext/clojure-sdk on clojars.org by default.
This SDK is built on top of
lsp4clj, which solves the
hard part of handling all the edge-cases of a JSON-RPC based server. I
built this layer by hand and discovered all the edge-cases before
realising that lsp4clj
was the smarter approach. The code is super
well written and easy to modify for my requirements.
Copyright © 2025 Unravel.tech
Distributed under the MIT License
{ "mcpServers": { "mcp-clojure-sdk": { "command": "java", "args": [ "-Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory", "-Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog", "-Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector", "-Dlog4j2.configurationFile=log4j2-mcp.xml", "-Dbabashka.json.provider=metosin/jsonista", "-Dlogging.level=INFO", "-cp", "/Users/vedang/mcp-clojure-sdk/examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar", "calculator_server" ] } } }
Related projects feature coming soon
Will recommend related projects based on sub-categories