mcp-clj

A Clojure implementation of the Model Context Protocol (MCP) with minimal dependencies and self-contained Clojure REPL integration.

Quick Start

# Add to deps.edn
{:deps {org.hugoduncan/mcp-clj
        {:git/url   "https://github.com/hugoduncan/mcp-clj"
         :git/sha   "latest-commit-sha"
         :deps/root "projects/server"}}}

;; Start MCP server
(require 'mcp-clj.mcp-server.core)
(def server (mcp-clj.mcp-server.core/create-server {:transport {:type :stdio}}))
;; Server exposes tools like clj-eval and ls

;; Connect with Claude Desktop via stdio transport (see Claude Desktop Setup)

Jump to: Installation • Client Usage • Claude Code Setup • Claude Desktop Setup • Development

What & Why

mcp-clj provides both MCP server and client implementations in Clojure:

- Self-contained REPL: Evaluates Clojure directly in the server process (no nREPL dependency)
- Low dependencies: Only requires org.clojure/data.json
- Multiple transports: SSE (HTTP), stdio, and in-memory for testing
- Built-in tools: Clojure evaluation (clj-eval) and file listing (ls) with gitignore support
- MCP client: Connect to other MCP servers from Clojure

When to use mcp-clj:
- Expose Clojure REPL functionality to Claude Desktop or other MCP clients
- Build Clojure applications that consume MCP services
- Simple deployment without external REPL dependencies

Trade-offs vs clojure-mcp:
- ✅ Simpler setup, self-contained evaluation
- ❌ Cannot connect to existing remote REPLs
- ❌ Fewer built-in tools

Installation

Git Dependencies (Recommended)

;; deps.edn
{:deps {org.hugoduncan/mcp-clj
        {:git/url   "https://github.com/hugoduncan/mcp-clj"
         :git/sha   "latest-commit-sha"  ; Replace with actual latest SHA
         :deps/root "projects/server"}}}

CLI Usage

# Clone and run directly
git clone https://github.com/hugoduncan/mcp-clj
cd mcp-clj
Start stdio server (recommended for Claude Desktop)
clj -M:stdio-server
Start SSE server (HTTP) on port 3001 (default)
clj -M:sse-server
Start SSE server on custom port
clj -M:sse-server --port 8080

Server Usage

Basic Server

(require 'mcp-clj.mcp-server.core)
;; Stdio server (recommended for Claude Desktop)

(def server (mcp-clj.mcp-server.core/create-server

             {:transport {:type :stdio}}))
;; SSE server (for HTTP-based clients)

(def server (mcp-clj.mcp-server.core/create-server

             {:transport {:type :sse :port 3001}}))
;; Stop server

((:stop server))

Custom Tools

(def echo-tool
  {:name "echo"
   :description "Echo the input text"
   :inputSchema {:type "object"
                 :properties {"text" {:type "string"}}
                 :required ["text"]}
   :implementation (fn [{:keys [text]}]
                     {:content [{:type "text" :text text}]
                      :isError false})})
;; Server with custom tools

(def server (mcp-clj.mcp-server.core/create-server

             {:transport {:type :sse :port 3001}

              :tools {"echo" echo-tool}}))
;; Add tools dynamically

(mcp-clj.mcp-server.core/add-tool! server echo-tool)

Built-in Tools

clj-eval: Evaluates Clojure expressions

{"name": "clj-eval", "arguments": {"code": "(+ 1 2 3)"}}

// Returns: "6"

ls: Lists files with gitignore support

{"name": "ls", "arguments": {"path": "src", "max-depth": 2, "max-files": 50}}

// Returns: {"files": [...], "truncated": false, "total-files": 12}

Client Usage

Connect to other MCP servers from Clojure:

(require 'mcp-clj.mcp-client.core)
;; Connect to stdio MCP server

(def client (mcp-clj.mcp-client.core/create-client

             {:transport {:type :stdio

                          :command "clojure"

                          :args ["-M:stdio-server"]}

              :client-info {:name "my-client" :version "1.0.0"}}))
;; Wait for connection

(mcp-clj.mcp-client.core/wait-for-ready client)
;; List available tools

(mcp-clj.mcp-client.core/list-tools client)

;; => {:tools [{:name "clj-eval" :description "..." :inputSchema {...}}]}
;; Call a tool

@(mcp-clj.mcp-client.core/call-tool client "clj-eval" {:code "( 6 7)"})

;; => {:content [{:type "text" :text "42"}] :isError false}

;; Cleanup

(.close client)

{:aliases
 {:mcp {:extra-deps {org.hugoduncan/mcp-clj
        {:git/url   "https://github.com/hugoduncan/mcp-clj"
         :git/sha   "latest-commit-sha"
         :deps/root "projects/server"}}
 :main-opts ["-m" "mcp-clj.stdio-server.main"]}}}

claude mcp add mcp-clj clojure -M:mcp

# Verify the MCP server is configured and accessible
claude mcp list

{:deps {org.hugoduncan/mcp-clj
        {:git/url   "https://github.com/hugoduncan/mcp-clj"
         :git/sha   "latest-commit-sha"
         :deps/root "projects/server"}}
:aliases

 {:mcp {:main-opts ["-m" "mcp-clj.stdio-server.main"]}}}

{
  "mcpServers": {
    "mcp-clj": {
      "command": "/opt/homebrew/bin/bash",
      "args": [
        "-c",
        "cd /path/to/your/project && clojure -M:mcp"
      ],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

git clone https://github.com/hugoduncan/mcp-clj
cd mcp-clj
Start REPL with all components
clj -M:dev

# Fast unit tests (default)
clj -M:kaocha:dev:test
Integration tests (starts servers)
clj -M:kaocha:dev:test --focus :integration
All tests
clj -M:kaocha:dev:test --focus :unit :integration
Specific namespace
clj -M:kaocha:dev:test --focus mcp-clj.mcp-server.core-test

;; After adding dependencies to deps.edn
(require 'clojure.repl.deps)
(clojure.repl.deps/sync-deps)
;; Reload namespace

(require 'my.namespace :reload)
;; Run tests

(require 'clojure.test)

(clojure.test/run-tests 'mcp-clj.mcp-server.core-test)

# macOS
brew install git-cliff
Or download from https://github.com/orhun/git-cliff/releases

# Preview unreleased changes
git cliff --unreleased
Update CHANGELOG.md
git cliff -o CHANGELOG.md

- mcp-server/ - MCP protocol server with tools, prompts, resources
- mcp-client/ - MCP protocol client for connecting to servers
- json-rpc/ - JSON-RPC 2.0 with automatic EDN/JSON conversion
- tools/ - Built-in MCP tools (clj-eval, ls)
- -transport/ - Multiple transport layers (SSE, stdio, HTTP, in-memory)

All components use the mcp-clj namespace and follow JSON-RPC 2.0 with MCP protocol version 2024-11-05.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes and ensure tests pass: clj -M:kaocha:dev:test
4. Submit a pull request

License

MIT License. See LICENSE file for details.