Skip to content
Back to search

clojure-mcp

Clojure MCP

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bhauman--clojure-mcp/badge.svg)](/listings/bhauman--clojure-mcp)

HTML

<a href="/listings/bhauman--clojure-mcp"><img src="/api/listings/bhauman--clojure-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- [Clojure](https://clojure.org/guides/install_clojure) - [Java](https://openjdk.org/) (JDK 17 or later) - An nREPL in your project (see [doc/nrepl.md](doc/nrepl.md)), or let ClojureMCP start one with `:start-nrepl-cmd` or `:fallback-nrepl` - Full toolkit only: [ripgrep](https://github.com/BurntSushi/ripgrep#installation) for better `grep` and `glob_files` performance

Install ClojureMCP

Install ClojureMCP using the Clojure tools installer:

clojure -Ttools install-latest :lib io.github.bhauman/clojure-mcp :as mcp

This installs ClojureMCP globally, making `clojure -Tmcp start` available from any directory.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 381 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Clojure MCP: A Live REPL for Your Coding Agent
  2. ClojureMCP gives coding agents like Claude Code and Codex a persistent
  3. connection to your Clojure REPL.
  4. ## Table of Contents
  5. - [What is ClojureMCP?](#what-is-clojuremcp)
  6. - [Where the project is headed](#where-the-project-is-headed)
  7. - [Help and Community Resources](#help-and-community-resources)
  8. - [📋 Installation](#-installation)
  9. - [CLI Agents (recommended)](#cli-agents-recommended)
  10. - [The Full Toolkit (legacy)](#the-full-toolkit-legacy)
  11. - [🔧 Customization](#-customization)
  12. - [CLI Options](#cli-options)
  13. - [⚙️ Configuration](#-configuration)
  14. - [📝 License](#-license)
  15. ## What is ClojureMCP?
  16. ClojureMCP is an MCP server that connects a coding agent to a running
  17. nREPL in your project. With it, the agent can do what Clojure
  18. programmers do: explore in the REPL, check its assumptions against
  19. the running program, and test changes as it makes them.
  20. - **`clojure_eval`** - evaluates code over a persistent nREPL
  21. connection, repairing unbalanced delimiters before evaluating.
  22. Works with Clojure, ClojureScript (shadow-cljs, Figwheel),
  23. Babashka, Basilisp, and Scittle.
  24. - **`list_nrepl_ports`** - discovers the nREPL servers running on
  25. your machine, so the agent can find and switch between REPLs.
  26. - **`paren_repair`** - a safety valve for the rare delimiter tangle
  27. that's hard to fix by string editing.
  28. That's the whole recommended setup: the `:repl` profile. Your agent
  29. keeps its own file reading, editing, search and shell tools.
  30. ## Where the project is headed
  31. ClojureMCP began in 2025 as a complete coding toolkit for Claude
  32. Desktop, at a time when LLMs regularly mangled Clojure's parentheses.
  33. So it shipped its own structure-aware editors (`clojure_edit`,
  34. `clojure_edit_replace_sexp`), a collapsed `read_file`, file and shell
  35. tools, sub-agents, prompts and resources.
  36. That has changed. Current frontier models (recent Claude models in
  37. particular) edit Clojure reliably with the built-in editors of Claude
  38. Code and Codex, and they rarely get into delimiter trouble they can't
  39. get out of. The part of ClojureMCP that still matters is the REPL.
  40. So:
  41. - **The `:repl` profile is the recommended way to use ClojureMCP.**
  42. - **The editing tools and the rest of the full toolkit still work**
  43. and remain available. They're useful if you're building your own
  44. harness, or if you're driving a model that does struggle with
  45. Clojure edits. But they're in maintenance mode and on a long path
  46. to deprecation, unless new, effective LLM editing approaches are
  47. discovered that are best delivered through ClojureMCP.
  48. ## Help and Community Resources
  49. * The [#ai-assisted-coding Channel on Clojurians Slack](https://clojurians.slack.com/archives/C068E9L5M2Q) is very active and where I spend a lot of time.
  50. * The [ClojureMCP Wiki](https://github.com/bhauman/clojure-mcp/wiki) has info on various integrations and sandboxing.
  51. ## 📋 Installation
  52. ### Prerequisites
  53. - [Clojure](https://clojure.org/guides/install_clojure)
  54. - [Java](https://openjdk.org/) (JDK 17 or later)
  55. - An nREPL in your project (see [doc/nrepl.md](doc/nrepl.md)), or let ClojureMCP start one with `:start-nrepl-cmd` or `:fallback-nrepl`
  56. - Full toolkit only: [ripgrep](https://github.com/BurntSushi/ripgrep#installation) for better `grep` and `glob_files` performance
  57. ### Install ClojureMCP
  58. Install ClojureMCP using the Clojure tools installer:
  59. ```bash
  60. clojure -Ttools install-latest :lib io.github.bhauman/clojure-mcp :as mcp
  61. ```
  62. This installs ClojureMCP globally, making `clojure -Tmcp start` available from any directory.
  63. ## CLI Agents (recommended)
  64. CLI coding agents (Claude Code, Codex, Gemini CLI) already have
  65. excellent file editing, search and shell tools. ClojureMCP adds the
  66. one thing they're missing: a live REPL.
  67. ### Adding ClojureMCP with `:repl`
  68. Run from your project directory:
  69. ```bash
  70. # Claude Code
  71. claude mcp add clojure-mcp -- clojure -Tmcp start :config-profile :repl
  72. # OpenAI Codex
  73. codex mcp add clojure-mcp -- clojure -Tmcp start :config-profile :repl
  74. # Google Gemini CLI
  75. gemini mcp add clojure-mcp clojure -Tmcp start :config-profile :repl
  76. ```
  77. By default ClojureMCP connects to the nREPL port in your project's
  78. `.nrepl-port` file. If you don't keep a REPL running, add
  79. `:fallback-nrepl true` to have ClojureMCP start one for you, or
  80. `:start-nrepl-cmd '["clojure" "-M:nrepl"]'` to start your own alias.
  81. **Why an MCP tool instead of evaluating via the shell?** Agents
  82. reach for a first-class REPL tool far more readily than for a shell
  83. command, and the connection is persistent: state you build up in the
  84. REPL stays there between evaluations. If you'd rather not run an MCP
  85. server at all, [clojure-mcp-light](https://github.com/bhauman/clojure-mcp-light)
  86. provides a shell-based nREPL client and a delimiter-repair hook instead.
  87. ### Working with Multiple REPLs
  88. 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.
  89. ### Older CLI profiles
  90. These editing-focused profiles are still shipped. They're mainly
  91. useful with models that struggle to edit Clojure.
  92. All three include the `:repl` tools (`clojure_eval`,
  93. `list_nrepl_ports`, `paren_repair`) plus `deps_list`, `deps_grep` and
  94. `deps_read` for searching and reading source in dependency jars.
  95. - **`:cli-assist`** - structural editors as a fallback for when the
  96. host's Edit tool fails to apply a change.
  97. Adds: `clojure_edit`, `clojure_edit_replace_sexp`.
  98. - **`:cli-assist-agent`** - like `:cli-assist`, but the form-level
  99. fallback is an LLM sub-agent that applies loosely specified edits
  100. (requires an API key).
  101. Adds: `clojure_edit_agent`, `clojure_edit_replace_sexp`.
  102. - **`:cli-assist-full`** - all Clojure reading and editing routed
  103. through ClojureMCP's tools instead of the host's.
  104. Adds: `read_file`, `clojure_edit`, `clojure_edit_replace_sexp`.
  105. See [doc/full-toolkit.md](doc/full-toolkit.md#editing-profiles-for-cli-agents) for more.
  106. ### Check install by starting the server
  107. From your project directory:
  108. ```bash
  109. clojure -Tmcp start :config-profile :repl
  110. ```
  111. You should see JSON-RPC output like this:
  112. ```json
  113. {"jsonrpc":"2.0","method":"notifications/tools/list_changed"}
  114. {"jsonrpc":"2.0","method":"notifications/tools/list_changed"}
  115. {"jsonrpc":"2.0","method":"notifications/resources/list_changed"}
  116. {"jsonrpc":"2.0","method":"notifications/prompts/list_changed"}
  117. ```
  118. ## The Full Toolkit (legacy)
  119. Without a `:config-profile`, ClojureMCP serves its original full
  120. toolkit: structure-aware editors, a collapsed file reader, file and
  121. shell tools, sub-agents, prompts and resources. It was built to turn
  122. Claude Desktop into a Clojure coding assistant, and it's in
  123. maintenance mode now (see
  124. [Where the project is headed](#where-the-project-is-headed)).
  125. If you're reaching for Claude Desktop to write Clojure, you'll be
  126. better served by Claude Code, Codex or another programming harness
  127. with the [`:repl` profile](#cli-agents-recommended).
  128. Setup for Claude Desktop, the older editing profiles, API keys for
  129. the agent tools, the full tool list and file-tool configuration are
  130. all in **[doc/full-toolkit.md](doc/full-toolkit.md)**.
  131. ## 🔧 Customization
  132. If you're building your own harness, ClojureMCP's tools, prompts and
  133. resources can be assembled into a custom MCP server: pick the tools
  134. you want, add your own as multimethods or simple maps, and expose your
  135. own prompts and resources.
  136. See [Creating Your Own Custom MCP Server](doc/custom-mcp-server.md) to
  137. get started, and the [customization docs](doc/README.md) for the rest.
  138. ## CLI options
  139. Values passed to `clojure -Tmcp start` are EDN values.
  140. #### `:port`
  141. **Optional** - The nREPL server port to connect to. When using `:start-nrepl-cmd` without `:port`, the port will be automatically discovered from the command output.
  142. `:port 7888`
  143. #### `:host`
  144. **Optional** - The nREPL server host. Defaults to localhost if not specified.
  145. `:host "localhost"` or `:host "0.0.0.0"`
  146. #### `:not-cwd`
  147. **Optional** - If true, don't use the current working directory as the project directory. Requires `:port` to be specified. The MCP server will introspect the nREPL connection to discover the project's working directory. Needed for clients that launch the MCP server outside your project directory, such as Claude Desktop.
  148. `:not-cwd true`
  149. #### `:start-nrepl-cmd`
  150. **Optional** - A command to automatically start an nREPL server if one is not already running. Must be specified as a vector of strings. The MCP server will start this process and manage its lifecycle.
  151. When used without `:port`, the MCP server will automatically parse the port from the command's output. When used with `:port`, it will use that fixed port instead.
  152. **Important**: The nREPL server is started in the current working directory, so launch `clojure-mcp` from your project directory (where your `deps.edn` or `project.clj` is located). CLI agents do this already. For clients that launch servers elsewhere, also pass `:project-dir`.
  153. `:start-nrepl-cmd ["lein" "repl" ":headless"]` or `:start-nrepl-cmd ["clojure" "-M:nrepl"]`
  154. #### `:fallback-nrepl`
  155. **Optional** - When `true`, ClojureMCP will first try to attach to `:port`. If nothing is listening there (or `:port` is omitted entirely), it spawns a local nREPL on an **ephemeral** port and connects to that. The fallback never squats on your configured `:port`, so a later editor session can still claim it.
  156. This is intended for users who don't always have an editor-managed nREPL running. Without this flag, ClojureMCP fails to start if it can't reach `:port`.
  157. The default command is built from clojure-mcp's own nREPL dependency (so no version is hardcoded) and runs through `clojure -Sdeps ... -M -m nrepl.cmdline`. The user's `~/.clojure/deps.edn` is still merged in by the `clojure` CLI, so libraries you keep globally available (e.g. Criterium) remain on the spawned REPL's classpath.
  158. The spawned process is cleaned up automatically when the MCP server shuts down.
  159. `:fallback-nrepl true`
  160. #### `:fallback-nrepl-cmd`
  161. **Optional** - Overrides the default fallback command. Must be a vector of strings. Only used when `:fallback-nrepl` is `true`. Do not include an explicit port in the command; the launcher needs to parse the discovered port from the process output.
  162. `:fallback-nrepl-cmd ["lein" "repl" ":headless"]`
  163. #### `:fallback-nrepl-dir`
  164. **Optional** - Working directory for the spawned fallback REPL. Defaults to `:project-dir` if set, otherwise to `$HOME`. Useful when you want the fallback REPL to pick up a project's `deps.edn` automatically.
  165. `:fallback-nrepl-dir "/path/to/scratch"`
  166. #### `:config-file`
  167. **Optional** - Specify the location of a configuration file. Must be a path to an existing file.
  168. `:config-file "/path/to/config.edn"`
  169. #### `:project-dir`
  170. **Optional** - Specify the working directory for your codebase. This overrides the automatic introspection of the project directory from the nREPL connection. Must be a path to an existing directory.
  171. `:project-dir "/path/to/your/clojure/project"`
  172. #### `:nrepl-env-type`
  173. **Optional** - Specify the type of environment that we are connecting to over the nREPL connection. This overrides automatic detection. Valid options are:
  174. * `:clj` for Clojure or ClojureScript
  175. * `:bb` for [Babashka](https://babashka.org/) - Native, fast starting Clojure interpreter for scripting
  176. * `:basilisp` for [Basilisp](https://basilisp.readthedocs.io/) - A Clojure-compatible Lisp dialect targeting Python 3.9+
  177. * `:scittle` for [Scittle](https://github.com/babashka/scittle) - Execute ClojureScript directly from browser script tags
  178. `:nrepl-env-type :bb`
  179. #### `:shadow-cljs-repl-message`
  180. **Optional** - Controls whether the shadow-cljs REPL mode status message is included in eval results (default: `true`). When connected to a shadow-cljs nREPL, a status message about CLJS mode is prepended to every eval result. Set to `false` to disable this message.
  181. `:shadow-cljs-repl-message false`
  182. #### `:config-profile`
  183. **Optional** - Load a built-in configuration profile that adjusts tool availability and descriptions. Useful for tailoring ClojureMCP to specific use cases.
  184. Available profiles:
  185. * `:repl` - **Recommended.** REPL-only toolset for CLI coding agents (Claude Code, Codex, Gemini CLI): `clojure_eval`, `list_nrepl_ports` and `paren_repair`, with no prompts or resources. The agent uses its own tools for all reading and editing. Uses allowlists, so tools added to ClojureMCP later stay off unless the profile lists them.
  186. * `:cli-assist`, `:cli-assist-agent`, `:cli-assist-full` - *(legacy)* Editing-focused profiles; see [doc/full-toolkit.md](doc/full-toolkit.md#editing-profiles-for-cli-agents).
  187. `:config-profile :repl`
  188. #### `:enable-tools`
  189. **Optional** - Allowlist of tool keywords. When provided, replaces any `:enable-tools` value from config. Only the listed tools will be available.
  190. `:enable-tools [:clojure_eval :read_file]`
  191. #### `:disable-tools`
  192. **Optional** - Blocklist of tool keywords. When provided, replaces any `:disable-tools` value from config. The listed tools will be disabled.
  193. `:disable-tools [:bash :dispatch_agent]`
  194. #### `:add-tools`
  195. **Optional** - Force-enable specific tools after config resolution. Removes tools from the disable list, and adds them to the enable list if one is active. This is useful for selectively re-enabling tools that a config profile disables.
  196. `:add-tools [:my_custom_agent]`
  197. #### `:remove-tools`
  198. **Optional** - Force-disable specific tools after config resolution. Adds tools to the disable list, and removes them from the enable list if one is active. This is useful for selectively disabling tools without replacing the entire config.
  199. `:remove-tools [:clojure_eval]`
  200. #### Tool filtering application order
  201. 1. Config loaded (home + project + profile merge)
  202. 2. `:enable-tools`/`:disable-tools` from opts replace config values (if provided)
  203. 3. `:remove-tools` applied (force-disable)
  204. 4. `:add-tools` applied (force-enable — wins over `:remove-tools` on overlap)
  205. 5. `ENABLE_TOOLS`/`DISABLE_TOOLS` env vars still win over everything
  206. See [Component Filtering](doc/component-filtering.md) for details on how enable/disable lists work in config files.
  207. ### Example Usage
  208. ```bash
  209. # Recommended for CLI coding agents: REPL tools only
  210. clojure -Tmcp start :config-profile :repl
  211. # REPL only, connecting to a specific port
  212. clojure -Tmcp start :config-profile :repl :port 7888
  213. # REPL only, spawning an nREPL if none is running
  214. clojure -Tmcp start :config-profile :repl :fallback-nrepl true
  215. # REPL only, starting your project's nREPL alias (port is discovered)
  216. clojure -Tmcp start :config-profile :repl :start-nrepl-cmd '["clojure" "-M:nrepl"]'
  217. # Leiningen project
  218. clojure -Tmcp start :config-profile :repl :start-nrepl-cmd '["lein" "repl" ":headless"]'
  219. # Babashka nREPL
  220. clojure -Tmcp start :config-profile :repl :port 1667 :nrepl-env-type :bb
  221. # With custom host and project directory
  222. clojure -Tmcp start :port 7888 :host '"0.0.0.0"' :project-dir '"/path/to/project"'
  223. # Using a custom config file
  224. clojure -Tmcp start :port 7888 :config-file '"/path/to/custom-config.edn"'
  225. # REPL only, plus one of the legacy structural editors
  226. clojure -Tmcp start :config-profile :repl :add-tools '[:clojure_edit]'
  227. # Strictly REPL: drop paren_repair too
  228. clojure -Tmcp start :config-profile :repl :remove-tools '[:paren_repair]'
  229. # Full override — only these two tools
  230. clojure -Tmcp start :enable-tools '[:clojure_eval :read_file]'
  231. ```
  232. **Note**: String values need to be properly quoted for the shell, hence `'"value"'` syntax for strings.
  233. ## ⚙️ Configuration
  234. ClojureMCP reads optional project configuration from a
  235. `.clojure-mcp/config.edn` file in your project's root directory. The
  236. `:repl` profile usually needs none. Most options configure the full
  237. toolkit's file, shell and agent tools (see
  238. [doc/full-toolkit.md](doc/full-toolkit.md#file-tool-configuration)).
  239. ### Configuration File Location
  240. Create a `.clojure-mcp/config.edn` file in your project root:
  241. ```
  242. your-project/
  243. ├── .clojure-mcp/
  244. │ └── config.edn
  245. ├── src/
  246. ├── deps.edn
  247. └── ...
  248. ```
  249. ### Configuration Options
  250. All options are documented in [CONFIG.md](CONFIG.md).
  251. ## 📝 License
  252. Eclipse Public License - v 2.0
  253. Copyright (c) 2025 Bruce Hauman
  254. This program and the accompanying materials are made available under the
  255. terms of the Eclipse Public License 2.0 which is available at
  256. http://www.eclipse.org/legal/epl-2.0
  257. ### License Summary
  258. - ✅ **Use freely** for personal projects, internal business tools, and development
  259. - ✅ **Modify and distribute** - improvements and forks are welcome
  260. - ✅ **Commercial use** - businesses can use this commercially without restrictions
  261. - ✅ **Flexible licensing** - can be combined with proprietary code
  262. - 📤 **Share improvements** - source code must be made available when distributed

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.