bhauman/clojure-mcp

ClojureMCP gives coding agents like Claude Code and Codex a persistent
connection to your Clojure REPL.
Table of Contents
- What is ClojureMCP?
- Where the project is headed
- Help and Community Resources
- 📋 Installation
- CLI Agents (recommended)
- The Full Toolkit (legacy)
- 🔧 Customization
- CLI Options
- ⚙️ Configuration
- 📝 License
What is ClojureMCP?
ClojureMCP is an MCP server that connects a coding agent to a running
nREPL in your project. With it, the agent can do what Clojure
programmers do: explore in the REPL, check its assumptions against
the running program, and test changes as it makes them.
- **clojure_eval** - evaluates code over a persistent nREPL
connection, repairing unbalanced delimiters before evaluating.
Works with Clojure, ClojureScript (shadow-cljs, Figwheel),
Babashka, Basilisp, and Scittle.
- **list_nrepl_ports** - discovers the nREPL servers running on
your machine, so the agent can find and switch between REPLs.
- **paren_repair** - a safety valve for the rare delimiter tangle
that's hard to fix by string editing.
That's the whole recommended setup: the :repl profile. Your agent
keeps its own file reading, editing, search and shell tools.
Where the project is headed
ClojureMCP began in 2025 as a complete coding toolkit for Claude
Desktop, at a time when LLMs regularly mangled Clojure's parentheses.
So it shipped its own structure-aware editors (clojure_edit,
clojure_edit_replace_sexp), a collapsed read_file, file and shell
tools, sub-agents, prompts and resources.
That has changed. Current frontier models (recent Claude models in
particular) edit Clojure reliably with the built-in editors of Claude
Code and Codex, and they rarely get into delimiter trouble they can't
get out of. The part of ClojureMCP that still matters is the REPL.
So:
- **The :repl profile is the recommended way to use ClojureMCP.**
- **The editing tools and the rest of the full toolkit still work**
and remain available. They're useful if you're building your own
harness, or if you're driving a model that does struggle with
Clojure edits. But they're in maintenance mode and on a long path
to deprecation, unless new, effective LLM editing approaches are
discovered that are best delivered through ClojureMCP.
Help and Community Resources
* The #ai-assisted-coding Channel on Clojurians Slack is very active and where I spend a lot of time.
* The ClojureMCP Wiki has info on various integrations and sandboxing.
📋 Installation
Prerequisites
- Clojure
- Java (JDK 17 or later)
- An nREPL in your project (see doc/nrepl.md), or let ClojureMCP start one with :start-nrepl-cmd or :fallback-nrepl
- Full toolkit only: ripgrep for better grep and glob_files performance
Install ClojureMCP
Install ClojureMCP using the Clojure tools installer:
This installs ClojureMCP globally, making clojure -Tmcp start available from any directory.
CLI Agents (recommended)
CLI coding agents (Claude Code, Codex, Gemini CLI) already have
excellent file editing, search and shell tools. ClojureMCP adds the
one thing they're missing: a live REPL.
Adding ClojureMCP with :repl
Run from your project directory:
By default ClojureMCP connects to the nREPL port in your project's
.nrepl-port file. If you don't keep a REPL running, add
:fallback-nrepl true to have ClojureMCP start one for you, or
:start-nrepl-cmd '["clojure" "-M:nrepl"]' to start your own alias.
**Why an MCP tool instead of evaluating via the shell?** Agents
reach for a first-class REPL tool far more readily than for a shell
command, and the connection is persistent: state you build up in the
REPL stays there between evaluations. If you'd rather not run an MCP
server at all, clojure-mcp-light
provides a shell-based nREPL client and a delimiter-repair hook instead.
Working with Multiple REPLs
With list_nrepl_ports, the agent can discover both your Clojure and shadow-cljs REPLs simultaneously. The tool identifies which REPLs are shadow-cljs instances, allowing the agent to evaluate on either REPL using clojure_eval with the appropriate port parameter.