mcp-clojure-sdk

View on GitHub

A Clojure SDK to create MCP servers (and eventually clients)

54 stars ClojureDeveloper Kits Updated Oct 30, 2025

Documentation

io.modelcontext/clojure-sdk

A `clojure-sdk` for creating Model Context Protocol servers!

Table of Contents :TOC_4:

io.modelcontext/clojure-sdk

Usage

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](examples/README.md) (also copied below this section)

Deps

The deps for `clojure-sdk` are:

clojure

{io.modelcontextprotocol/mcp-clojure-sdk
 {:git/url "https://github.com/unravel-team/mcp-clojure-sdk.git"
  :git/sha "d42474c5f66b6f5ad1e4d6ce2a4e8972640fb831"}}

Templates for Quickstart

For your ease of use, there is also a `deps-new` template and a Github template. See:

1. mcp-clojure-server-deps-new

for a `deps-new` based template to quickly create new MCP servers.

2. example-cool-mcp-server

for a Github template project to quickly create new MCP servers.

Examples

Building the Examples Jar

$ make clean && make examples-jar

The examples jar contains the following servers:

1. Calculator: `calculator_server`

2. Vega-lite: `vegalite_server`

3. Code Analysis: `code_analysis_server`

Calculator: `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:

1. What's the average of [1, 2, 3, 4, 5]?

2. What's the factorial of 15?

3. What's 2 to the power of 1000?

4. What's the square-root of 64?

Before running the calculator MCP server:

Remember:

1. Use the full-path to the examples JAR on your system

In Claude Desktop

json

"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"
      ]
    }

In MCP Inspector

shell

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

Vega-lite: `vegalite_server`

Provides tools for generating Vega-lite charts: `save-data`,

`visualize-data`.

PRE-REQUISITES: Needs [vl-convert

CLI](https://github.com/vega/vl-convert) to be installed.

Some example commands you can try in Claude Desktop or Inspector:

Here is some example data for you:

json

[
    { "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.

Before running the vegalite MCP server

Remember:

1. Replace the full-path to the examples JAR with the correct path on

your system

2. Specify the full-path to `vl-convert` on your system

In Claude Desktop

json

"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"
      ]
    }

In MCP Inspector

Remember to use the full-path to the examples JAR on your system, or

execute this command from the `mcp-clojure-sdk` repo.

shell

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: `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.

Before running the code-analysis MCP server

Remember:

1. Replace the full-path to the examples JAR with the correct path on

your system

In Claude Desktop

json

"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"
      ]
    }

In MCP Inspector

(Remember to use the full-path to the examples JAR on your system, or

execute this command from the `mcp-clojure-sdk` repo)

shell

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

Core Components

1. Server Implementation: The core server functionality is

implemented in `server.clj`, which handles request/response cycles

for various MCP methods.

2. 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.

3. Error Handling: Custom error handling is defined in

`mcp/errors.clj`.

4. Protocol Specifications: All protocol specifications are

defined in `specs.clj`, which provides validation for requests,

responses, and server components.

Communication Flow

The sequence diagram shows the typical lifecycle of an MCP

client-server interaction:

1. Initialization Phase:

2. Discovery Phase:

using methods `tools/list`, `resources/list` and `prompts/list`

3. Tool Interaction:

4. Resource Interaction:

5. Prompt Interaction:

6. Optional Features:

mermaid

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

Pending Work

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.

Development of the SDK

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.

Inspiration

This SDK is built on top of

jsonrpc4clj, 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 `jsonrpc4clj` was the smarter

approach. The code is super well written and easy to modify for my

requirements.

License

Distributed under the MIT License

Frequently asked questions

What is mcp-clojure-sdk?

mcp-clojure-sdk is A Clojure SDK to create MCP servers (and eventually clients)

How do I install mcp-clojure-sdk?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is mcp-clojure-sdk open source?

Yes — it is hosted on GitHub at https://github.com/unravel-team/mcp-clojure-sdk and has 54 stars.

Related MCP tools

clojure-mcp

Clojure MCP Trusted by 600+ developers. Trusted by 600+ developers. Trusted by 600+ developers.

612 Clojure

typescript-sdk

The official TypeScript SDK for Model Context Protocol servers and clients Trusted by 10500+ developers. Trusted by 10500+ developers.

10,586 TypeScript

inspector

Visual testing tool for MCP servers TypeScript-based implementation. Trusted by 7300+ developers. Trusted by 7300+ developers.

7,373 TypeScript

mcp

AWS MCP Servers — helping you get the most out of AWS, wherever you use MCP. Python-based implementation. Trusted by 6900+ developers.

6,922 Python

awsmcpmcp-client+6

awesome-mcp-clients

A collection of MCP clients. Trusted by 5900+ developers. Trusted by 5900+ developers. Trusted by 5900+ developers. Trusted by 5900+ developers.

5,959

clientsmcp

awesome-mcp-zh

MCP 资源精选， MCP指南，Claude MCP，MCP Servers, MCP Clients Trusted by 4800+ developers. Trusted by 4800+ developers. Trusted by 4800+ developers.

4,870

claudeclaude-mcpdeepseek+9

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP