mcp-clj

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)

Claude Code Setup

Claude Code can connect to mcp-clj servers using the stdio transport.

1. Add mcp-clj to your project

In your deps.edn:

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

2. Configure Claude Code

Add the MCP server using Claude Code's CLI:

claude mcp add mcp-clj clojure -M:mcp

3. Test the connection

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

You should see mcp-clj in the list of available servers. Claude Code will now have access to clj-eval and ls tools within your project context.

Claude Desktop Setup

Claude Desktop can connect directly to mcp-clj using the stdio transport without requiring additional proxy tools.

1. Add mcp-clj to your project

In your deps.edn:

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

2. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Note: Replace /path/to/your/project with your actual project directory and adjust the bash path if needed (which bash to find yours).

3. Restart Claude Desktop

Claude will now have access to clj-eval and ls tools running in your project's context.

Development

Setup

git clone https://github.com/hugoduncan/mcp-clj
cd mcp-clj

# Start REPL with all components
clj -M:dev

Testing

# 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

REPL Development

;; 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)

Changelog

See CHANGELOG.md for release notes and version history.

Generating Changelog Locally

Install git-cliff:

# macOS
brew install git-cliff

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

Generate changelog:

# Preview unreleased changes
git cliff --unreleased

# Update CHANGELOG.md
git cliff -o CHANGELOG.md

Architecture

mcp-clj uses a polylith-style architecture with component-based organization:

• Components (components/) - Reusable functionality (mcp-server, mcp-client, json-rpc, tools, etc.)
• Bases (bases/) - Entry points (sse-server, stdio-server)
• Projects (projects/server/) - Deployable artifacts

Key Components

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