ClojureMCP (Clojure MCP Server)
Author: bhauman
Description: ClojureMCP is an MCP (Model Context Protocol) server for Clojure that connects LLM clients (Claude Code/Claude Desktop/Codex/Gemini CLI) to a Clojure project via nREPL. It provides REPL evaluation plus Clojure-aware read/edit tooling (delimiter repair + structural edits) and optional agent-style tools that can call external LLM APIs. Core capabilities/tools exposed over MCP include: file tree listing (LS), smart file reading (read_file), grep/glob search (grep/glob_files), REPL evaluation (clojure_eval) and REPL discovery (list_nrepl_ports), shell command execution (bash), structure-aware Clojure edits (clojure_edit/clojure_edit_replace_sexp) plus generic edits/writes (file_edit/file_write). Optional/experimental: scratch_pad persistence, code_critique, dispatch_agent, architect. Agent tools may incur API charges if ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY are set.
Stars: 715
Forks: 78
License: Eclipse Public License 2.0
Category: Specialized
Overview
Installation
clojure -Ttools install-latest :lib io.github.bhauman/clojure-mcp :as mcpclojure -Tmcp start :config-profile :cli-assist# Claude Code
claude mcp add clojure-mcp -- clojure -Tmcp start :config-profile :cli-assist
# OpenAI Codex
codex mcp add clojure-mcp -- clojure -Tmcp start :config-profile :cli-assist
# Google Gemini CLI
gemini mcp add clojure-mcp clojure -Tmcp start :config-profile :cli-assistcd /path/to/your/project
clojure -M:nrepl{
"mcpServers": {
"clojure-mcp": {
"command": "/opt/homebrew/bin/bash",
"args": [
"-c",
"clojure -Tmcp start :not-cwd true :port 7888"
]
}
}
}{:allowed-directories ["." "src" "test" "resources" "dev" "/absolute/path/to/shared/code" "../sibling-project"]
:write-file-guard :partial-read
:cljfmt false
:bash-over-nrepl false}FAQs
What is the difference between ClojureMCP's full toolset mode and the :cli-assist profile, and when should I use each one?
Full toolset mode includes all tools (file editing, shell operations, REPL) for sandboxed clients like Claude Desktop that lack native filesystem access. The `:cli-assist` profile strips out file editing and shell tools because CLI assistants like Claude Code already have those capabilities; duplicating them creates tool confusion and wastes token budget. Use full toolset mode for desktop chat applications. Use `:cli-assist` for command-line tools that already have filesystem permissions, keeping ClojureMCP focused on REPL evaluation, structural editing, and dependency inspection. The `:cli-assist` profile also supports `:start-nrepl-cmd` for automatic REPL initialization.
How does ClojureMCP's structure-aware editing prevent unbalanced parentheses compared to regular text-based AI code generation?
ClojureMCP manipulates code at the abstract syntax tree level rather than as character strings. Tools like `clojure_edit` and `clojure_edit_replace_sexp` parse code into S-expressions and validate delimiter pairs before modifying any file. The `paren_repair` tool detects mismatched delimiters by analyzing the expression tree and applies corrections that understand Lisp form boundaries. Text-based generation predicts tokens sequentially with no grammatical enforcement, causing premature closures or unclosed expressions in nested forms. ClojureMCP enforces syntactic validity as a precondition for modification, turning paren-balancing from a post-generation cleanup into a structural guarantee.
Can I use ClojureMCP with multiple Clojure projects simultaneously, and how do I configure allowed-directories for cross-project workflows?
Yes. Configure `allowed-directories` in `.clojure-mcp/config.edn` with all relevant project root paths: `{:allowed-directories ["/path/to/project-a" "/path/to/project-b" "/shared/libs"]}` Each directory grants the assistant permission to use file operations, dependency inspection, and structural editing across those codebases. For multiple nREPL instances, use `list_nrepl_ports` to discover active connections, then pass the appropriate port to `clojure_eval` to target the correct REPL per project.
What are the prerequisites and step-by-step instructions for setting up ClojureMCP with Claude Code or other CLI-based AI assistants?
First, verify Clojure CLI tools are installed, then install ClojureMCP using the Clojure tool installer. For Claude Code, the registration command uses the `:cli-assist` profile, which removes redundant file-editing and shell tools. Optionally configure automatic nREPL startup with `:start-nrepl-cmd` to eliminate manual REPL management. For multi-project workflows, set `allowed-directories` in `.clojure-mcp/config.edn`. For faster dependency searching, install ripgrep via your system package manager, though the server functions without it using a built-in Clojure regex fallback.
How does ClojureMCP's deps_grep tool search inside JAR files, and what are the practical benefits for dependency inspection?
`deps_grep` extracts JAR contents via unzip and applies regex pattern matching, using ripgrep for performance when available and falling back to Clojure's native regex otherwise. It returns `jar:entry` paths pointing directly to matched locations within the archive. Practical benefits include: - Verifying how a third-party library implements a function before calling it - Tracing deprecation warnings or unexpected behavior to exact code in transitive dependencies - Confirming API signatures when documentation is incomplete Results combine with `deps_read` to inspect actual implementations, eliminating the context switch of manually downloading and extracting JARs.
Does ClojureMCP work with Cursor, VS Code Copilot, or Windsurf, and what are the known compatibility issues with non-Claude MCP clients?
Compatibility depends on each client's MCP protocol implementation. Cursor has a documented protocol break with ClojureMCP's stdio communication; an SDK fix was merged but pending release as of the issue filing. VS Code Copilot and Windsurf remain untested. Common issues across non-Claude clients include aggressive stdio timeouts conflicting with REPL evaluation latency, synchronous response expectations mishandling nREPL's asynchronous protocol, and missing working directory context breaking relative path resolution. The `:cli-assist` profile may improve compatibility for terminal-based clients by reducing the tool surface area exposed to the protocol layer.