Repository files navigation

⚠️ Alpha Software - Work in Progress

Clojure MCP connects AI models to your Clojure developmentenvironment, enabling a remarkable REPL-driven development experiencepowered by large language models (LLMs).

Clojure MCP transforms LLMs into:

• Powerful Clojure Coding assistants.
• Powerful Clojure REPL assistants: Rapid evaluation, debugging, and iteration.
• Clojure-aware editors: Syntax-aware editing, auto-linting, and paren balancing.

With Clojure MCP alone you can turn an LLM into a powerful ClojureREPL and coding assistant.

LLMs excel in the Clojure REPL: Current LLMs are unarguablyfantastic Clojure REPL assistants that perform evaluations quickly andmuch more effectively than you can imagine. Ask anyone who hasexperienced this and they will tell you that the LLMs are performingmuch better in the Clojure REPL than they would haveimagined. Additionally, we must remember that the form andmaintainability of ephemeral code DOES NOT MATTER.

Buttery Smooth Clojure Editing: With current editing tools, LLMsstill struggle with the parenthesis. Clojure MCP has a different takeon editing that increases edit acceptance rates significantly. ClojureMCP lints code coming in, fixes parenthesis if possible, usesclj-rewrite to apply syntax aware patches, and then lints and formatsthe final result. This is a powerful editing pipeline that vastlyoutperforms when it comes to editing Clojure Code.

Together these two features along with a set of other Clojure awaretools create a new and unique LLM development experience that youprobably should try at least once to understand how transformationalit is.

• The Good News
• 🚀 Overview
• Main Features
  • Why REPL-Driven Development with AI?
• 🧠 Model Compatibility
• Cohesive Clojure Toolbox
  • Why These Tools Work as a Complete System
  • Using with Claude Code and Other Code Assistants
• Help and Community Resources
• 📋 Installation
  • Prerequisites
• Setting up ClojureMCP
  • Installation Overview
  • Step 1: Configure Your Target Project's nREPL Connection
  • Step 2: Install the Clojure MCP Server
  • Step 3: Configure Claude Desktop
  • Step 4: Test the Complete Setup
  • Troubleshooting Tips
  • Other Clients besides Claude Desktop
• Starting a new conversation
• Project Summary Management
• Chat Session Summarize and Resume
• Working with ClojureScript (shadow-cljs)
  • Quick Start
  • Switching Back to Clojure
  • Tips for shadow-cljs Development
• LLM API Keys
• Learning Curve
• 🧰 Available Tools
  • Read-Only Tools
  • Code Evaluation
  • File Editing Tools
  • Agent Tools (Require API Keys)
  • Experimental Tools
  • Key Tool Features
• 🔧 Customization
• ⚙️ Configuration
  • Configuration File Location
  • Configuration Options
  • Example Configuration
  • Configuration Details
  • Common Configuration Patterns
• 📜 Development Practices
  • Recommended Workflow
  • Best Practices
• 🔧 Project Maintenance
• 📚 Philosophy
• 📝 License
  • License Summary

There is a story that Clojure developers may have come to believe. Thestory that Modern LLMs are trained on vast amounts of code from mainstreamprogramming languages and as a result LLMs struggle to perform wellwhen working with niche languages like Clojure. I'm here to tell youthat this is just not true.

LLMs can definitely read and write Clojure. However, our the secretweapon is the REPL and how it provides a fast focused feedback loopfor LLMs to verify and refine code.

IMHO Clojure is an excellent language for LLM assisted development.All it needed was bit of a bridge... and this is what I've tried tocreate with ClojureMCP.

This project implements an MCP server that connects AI models to aClojure nREPL, and specialized Clojure editing tools enabling a uniqueClojure development experience.

Clojure MCP provides a superset of the tools that Claude Code uses,so you can use it to work on Clojurewithout any other tools.

I highly recommend using ClojureMCP with Claude Desktop tostart. Claude Desktop let's you see the complete reasoning and toolexecution chain which is very helpful for understanding how the LLMinteracts with the tools. Seeing the explicit reasoning and actions isinvaluable for learning how to work with LLMs as coding assistants.

• Clojure REPL Connection - which lints the eval and auto-balances parens
• Clojure Aware editing - Using clj-kondo, parinfer, cljfmt, and clj-rewrite
• Optimized set of tools for Clojure Development superset of Claude Code tools

For Clojurists an LLM assisted REPL is the killer application.

With a REPL LLMs can:

• Iterate on code in the REPL and when finished present the findings before adding them to your code
• Validate and probe your code for errors
• Debug your code in the REPL
• and much more

Additionally, in some LLM clients (including Claude Desktop), you cancontrol which tools are available to the model at any given moment soyou can easily remove the ability to edit files and restrict the modelto the REPL tool and force the use of the REPL.

These tools are designed to work with the latest LLM models. For the best experience with sexp editing and Clojure-specific tooling, we recommend:

• Anthropic Claude 3.7 andClaude 4.1 (sonnet or opus) (especiallyClaude 4.1 for best results)
• Gemini 2.5
• OpenAI o4-mini oro3 orchat-gpt-5

I highly recommendClaude 4.1 if you want to see long autonomousagentic action chains.

ClojureMCP's structural editing tools require high model performance,so using one of these recommended models will significantly improveyour experience.

I personally use Claude 4.1 Opus/Sonnet for almost everything,and I'm subscribed to Anthropic's $100US/month 5x Max plan. The valueI get out of it is far more than what I'm paying.

ClojureMCP can be used with almost any LLM client like Claude Desktop,Claude Code and many many more.

I use ClojureMCP with Claude Desktop because I can read the tooloutputs more clearly, which helps me understand how well the tools areperforming and if they are working well together to an LLM to behaveas an effective Clojure coding assistant.

I also use ClojureMCP with Claude Code and works great but I make sureto turn off many of the Claude Code tools that duplicate thefunctionality of the ClojureMCP tools.

While youcan use these tools alongside Claude Code and other codeassistants with their own tooling, I recommendtrying the ClojureMCP tools independently first to experience their fullcapabilities. Once you're comfortable with the Clojure MCP toolset,you can make informed decisions about whether to use it exclusively orintegrate it with other code assistants and development tools based onyour specific workflow needs.

• The#ai-assited-coding Channel the Clojurians Slack is very active and where I spend a lot of time.
• TheClojureMCP Wiki has info on various integrations and sandboxing.

• Clojure
• Java (JDK 17 or later)
• Claude Desktop (for the best experience)
• Optional but HIGHLY recommended:ripgrep for bettergrep andglob_files performance

Setting up ClojureMCP can be challenging as it is currently in alpha and not optimized for quick installation. This guide will walk you through the process step by step.

1. Configure nREPL: Set up and verify an nREPL server on port7888 in your project
2. Install ClojureMCP: Addclojure-mcp to your~/.clojure/deps.edn
3. Configure MCP Client: Set upclojure-mcp as an MCP server in Claude Desktop or other MCP clients
4. Install Riggrep (Optional):ripgrep is a smart, fast file search tool that respects.gitignore.

Note: This setup verifies that all components work together. You can customize specific configuration details (like port numbers) after confirming the basic setup works.

In the Clojure project where you want AI assistance, you'll need to ensure you can start an nREPL server on port7888 (you can use any port).

Add an:nrepl alias to your project'sdeps.edn:

{;; ... your project dependencies ...:aliases {;; nREPL server for AI to connect to;; Include all paths you want available for development:nrepl {:extra-paths ["test"]:extra-deps {nrepl/nrepl {:mvn/version"1.3.1"}};; this allows nrepl to interrupt runaway repl evals:jvm-opts ["-Djdk.attach.allowAttachSelf"]:main-opts ["-m""nrepl.cmdline""--port""7888"]}}}

Verify the configuration:

$ clojure -M:nrepl

You should see the nREPL server start on port7888.

Start an nREPL server with:

$ lein repl :headless :port 7888

Addclojure-mcp as an alias in your~/.clojure/deps.edn:

{:aliases  {:mcp    {:deps {org.slf4j/slf4j-nop {:mvn/version"2.0.16"};; Required for stdio server            com.bhauman/clojure-mcp {:git/url"https://github.com/bhauman/clojure-mcp.git":git/tag"v0.1.11-alpha":git/sha"7739dba"}}:exec-fn clojure-mcp.main/start-mcp-server:exec-args {:port7888}}}}

Finding the Latest Version: Visithttps://github.com/bhauman/clojure-mcp/commits/main for the latest commit SHA, or clone the repo and rungit log --oneline -1.

⚠️Important: You must have annREPL server running on port7888 before startingclojure-mcp.

1. First, start your nREPL server in your project directory:

   $ clojure -M:nrepl# or for Leiningen:$ lein repl :headless :port 7888

2. Then, in a new terminal, startclojure-mcp:

   $ clojure -X:mcp :port 7888

You should see JSON-RPC output like this:

{"jsonrpc":"2.0","method":"notifications/tools/list_changed"}{"jsonrpc":"2.0","method":"notifications/tools/list_changed"}{"jsonrpc":"2.0","method":"notifications/resources/list_changed"}{"jsonrpc":"2.0","method":"notifications/prompts/list_changed"}

Connection Refused Error:

Execution error (ConnectException) at sun.nio.ch.Net/connect0 (Net.java:-2).Connection refused

This meansclojure-mcp couldn't connect to your nREPL server. Ensure:

• The nREPL server is running
• The port numbers match (default: 7888)

Extraneous Output:If you see output other than JSON-RPC messages, it's likely due toclojure-mcp being included in a larger environment. Ensureclojure-mcp runs with its own isolated dependencies.

• Location Independence: The MCP server can run from any directory—it doesn't need to be in your project directory. It uses the nREPL connection for context.
• Shared Filesystem: Currently, the nREPL and MCP servers must run on the same machine as they assume a shared filesystem.
• Dependency Isolation: Don't includeclojure-mcp in your project's dependencies. It should run separately with its own deps. Always use:deps (not:extra-deps) in its alias.

The MCP server accepts the following command-line arguments viaclojure -X:mcp:

This is often the most challenging part—ensuring the application's launch environment has the correct PATH and environment variables.

Pick the shell executable that will most likely pick up your environment config:

If you are usingBash find the explicitbash executable path:

$ which bash/opt/homebrew/bin/bash

If you are usingZ Shell find the explicitzsh executable path:

$ which zsh/bin/zsh

Now we're going to use this explicit shell path in thecommandparameter in the Claude Desktop configuration as seen below.

Create or edit~/Library/Application\ Support/Claude/claude_desktop_config.json:

{"mcpServers": {"clojure-mcp": {"command":"/opt/homebrew/bin/bash","args": ["-c","clojure -X:mcp :port 7888"            ]        }    }}

1. Start nREPL in your target project:

   cd /path/to/your/projectclojure -M:nrepl

   Look for:nREPL server started on port 7888...

2. Restart Claude Desktop (required after configuration changes)

3. Verify Connection: In Claude Desktop, click the+ button in the chat area. You should see "Add from clojure-mcp" in the menu. It's important to note that it may take a few moments for this to show up.

4. If there was an error please see theTroubleshooting Tips. If it connected go see theStarting a new conversation section.

If Claude Desktop can't run theclojure command:

1. Test your command manually: Run the exact command from your config in a terminal
2. Check your PATH: Ensurewhich clojure works in a fresh terminal
3. Enable logging: Check Claude Desktop logs for error messages
4. Simplify first: Start with a basic configuration, then add complexity

If you continue to have issues, consider consulting with AI assistants (Claude, ChatGPT, Gemini) about the specific PATH configuration for your system setup.

If the aboveclaude_desktop_config.json doesn't work, it's mostlikely that thePATH environment variable is setup incorrectly tofindclojure andjava.

Depending on your setup you can fix this directly by altering thePATH environment variable:

{"mcpServers": {"clojure-mcp": {"command":"/opt/homebrew/bin/bash","args": ["-c","export PATH=/opt/homebrew/bin:$PATH; exec clojure -X:mcp :port 7888"            ]        }    }}

• Homebrew (Apple Silicon):/opt/homebrew/bin
• Homebrew (Intel Mac):/usr/local/bin
• Nix:/home/username/.nix-profile/bin or/nix/var/nix/profiles/default/bin
• System Default:/usr/bin:/usr/local/bin

These are some examples to give you a way to debug a failed ClojureMCP startup.

Examine the environment:

{"mcpServers": {"clojure-mcp": {"command":"/opt/homebrew/bin/bash","args": ["-c","echo $PATH > /Users/bruce/claude-desktop-path.txt"            ]        }    }}

Capture ClojureMCP output:

{"mcpServers": {"clojure-mcp": {"command":"/opt/homebrew/bin/bash","args": ["-c","clojure -X:mcp :port 7888 | tee /Users/bruce/clojure-mcp-stdout.log"            ]        }    }}

If you need to source environment variables (like API keys seeLLM API Keys) :

{"mcpServers": {"clojure-mcp": {"command":"/bin/sh","args": ["-c","source ~/.my-llm-api-keys.sh && PATH=/Users/username/.nix-profile/bin:$PATH && clojure -X:mcp :port 7888"            ]        }    }}

See theWiki forinformation on setting up other MCP clients.

Once everything is set up I'd suggest starting a new chat in Claude.

The first thing you are going to want to do is initialize contextabout the Clojure project in the conversation attached to the nREPL.

In Claude Desktop click the+ tools and optionally add

• resourcePROJECT_SUMMARY.md - (have the LLM create this) see below
• resourceClojure Project Info - which introspects the nREPL connected project
• resourceLLM_CODE_STYLE.md - Which is your personal coding style instructions (copy the one in this repo to the root of your project)
• promptclojure_repl_system_prompt - instructions on how to code - cribbed a bunch from Clod Code

Then start the chat.

I would start by stating a problem and then chatting with the LLM tointeractively design a solution. You can ask Claude to "propose" asolution to a problem.

Iterate on that a bit then have it either:

A. code and validate the idea in the REPL.

Don't underestimate LLMs abilities to use the REPL! Current LLMs areabsolutely fantastic at using the Clojure REPL.

B. ask the LLM to make the changes to the source code and then have it validate the code in the REPL after file editing.

C. ask to run the tests.D. ask to commit the changes.

Make a branch and have the LLM commit often so that it doesn't ruin good work by going in a bad direction.

1. Express the problem - Clearly state what you want to solve
2. Develop in the REPL - Work through solutions incrementally
3. Validate step-by-step - Test each expression before moving on
4. Save to files - When the solution is working, save it properly
5. Reload and verify - Make sure the saved code works

• Small steps - Prefer many small, valid steps over a few large steps
• Human guidance - Provide feedback to keep development on track
• Test early - Validate ideas directly in the REPL before committing to them

This project includes a workflow for maintaining an LLM-friendlyPROJECT_SUMMARY.md that helps assistants quickly understand the codebase structure.

1. Creating the Summary: To generate or update the PROJECT_SUMMARY.md file, use the MCP prompt in the+ >clojure-mcp menucreate-update-project-summary. This prompt will:

   • Analyze the codebase structure
   • Document key files, dependencies, and available tools
   • Generate comprehensive documentation in a format optimized for LLM assistants

2. Using the Summary: When starting a new conversation with an assistant:

   • The "Project Summary" resource automatically loads PROJECT_SUMMARY.md
   • This gives the assistant immediate context about the project structure
   • The assistant can provide more accurate help without lengthy exploration

3. Keeping It Updated: At the end of a productive session where new features or components were added:

   • Invoke thecreate-update-project-summary prompt again
   • The system will update the PROJECT_SUMMARY.md with newly added functionality
   • This ensures the summary stays current with ongoing development

This workflow creates a virtuous cycle where each session builds on the accumulated knowledge of previous sessions, making the assistant increasingly effective as your project evolves.

The Clojure MCP server provides a pair of prompts that enableconversation continuity across chat sessions using thescratch_padtool. By default, data is storedin memory only for the current session.To persist summaries across server restarts, you must enable scratch padpersistence using the configuration options described in the scratch pad section.

The system uses two complementary prompts:

1. chat-session-summarize: Creates a summary of the current conversation

   • Saves a detailed summary to the scratch pad
   • Captures what was done, what's being worked on, and what's next
   • Accepts an optionalchat_session_key parameter (defaults to"chat_session_summary")

2. chat-session-resume: Restores context from a previous conversation

   • Reads the PROJECT_SUMMARY.md file
   • Callsclojure_inspect_project for current project state
   • Retrieves the previous session summary from scratch pad
   • Provides a brief 8-line summary of where things left off
   • Accepts an optionalchat_session_key parameter (defaults to"chat_session_summary")

Ending a Session:

1. At the end of a productive conversation, invoke thechat-session-summarize prompt
2. The assistant will store a comprehensive summary in the scratch pad
3. This summary persists across sessions thanks to the scratch pad's global state

Starting a New Session:

1. When continuing work, invoke thechat-session-resume prompt
2. The assistant will load all relevant context and provide a brief summary
3. You can then continue where you left off with full context

You can maintain multiple parallel conversation contexts by using custom keys:

# For feature developmentchat-session-summarize with key "feature-auth-system"# For bug fixingchat-session-summarize with key "debug-memory-leak"# Resume specific contextchat-session-resume with key "feature-auth-system"

This enables switching between different development contexts while maintaining the full state of each conversation thread.

• Seamless Continuity: Pick up exactly where you left off
• Context Preservation: Important details aren't lost between sessions
• Multiple Contexts: Work on different features/bugs in parallel
• Reduced Repetition: No need to re-explain what you're working on

The chat summarization feature complements the PROJECT_SUMMARY.md by capturing conversation-specific context and decisions that haven't yet been formalized into project documentation.

ClojureMCP works seamlessly withshadow-cljs for ClojureScript development. Here's how to set it up:

1. Start your shadow-cljs server with an nREPL port:

   # Start shadow-cljs (it will use port 9000 by default, or configure in shadow-cljs.edn)npx shadow-cljs watch app

2. Configure Claude Desktop or other client to connect to the the shadow-cljs nREPL port:

   { "mcpServers": {     "clojure-mcp": {         "command": "/bin/sh",         "args": [             "-c",             "PATH=/opt/homebrew/bin:$PATH && clojure -X:mcp :port 9000"         ]     }  }}

OR change the shadow port to 7888 (or whatever port you have configured) and leave your client config as is.

3. Switch to ClojureScript REPL in Claude Desktop:

   Once Claude Desktop is connected, prompt Claude to evaluate:

   (shadow/repl:app)

   Replace:app with your actual build ID fromshadow-cljs.edn.

4. All set! Now allclojure_eval calls will be routed to your ClojureScript REPL, allowing you to:

   • Evaluate ClojureScript code
   • Interact with your running application
   • Use all ClojureMCP tools for ClojureScript development

To exit the ClojureScript REPL and return to Clojure, have Claude evaluate:

:cljs/quit

• Build Selection: Use the appropriate build ID (:app,:main,:test, etc.) based on yourshadow-cljs.edn configuration
• Hot Reload: shadow-cljs hot reload continues to work normally while using ClojureMCP
• Browser Connection: Ensure your browser is connected to shadow-cljs for browser-targeted builds
• Node.js Builds: Works equally well with Node.js targeted builds

This integration gives you the full power of ClojureMCP's REPL-driven development workflow for ClojureScript projects!

ClojureMCP even supports connecting to both REPLs at the same time!

Addclojure-mcp in dual mode as an alias in your~/.clojure/deps.edn,being sure to set the port (your nrepl port), shadow port, and shadow build as needed.

{:aliases  {:mcp-shadow-dual    {:deps {org.slf4j/slf4j-nop {:mvn/version"2.0.16"};; Required for stdio server            com.bhauman/clojure-mcp {:git/url"https://github.com/bhauman/clojure-mcp.git":git/tag"v0.1.11-alpha":git/sha"7739dba"}}:exec-fn clojure-mcp.main-examples.shadow-main/start-mcp-server:exec-args {:port7888:shadow-port7889:shadow-build"app"}}}}

Be sure to update yourclaude_desktop_config.json to use the new alias.Remember: You only need to provide arguments to the ClojureMCP server if you need to override the settings in yourdeps.edn.

Here is an example using the dual configuration:

Prompt to Claude:

Evaluate this expression in clojure:(+ 1 2 3)

Claude's response:

The expression (+ 1 2 3) evaluates to 6.This is a simple addition operation in Clojure where the + function adds all the arguments together: 1 + 2 + 3 = 6.

Now try ClojureScript:

Evaluate the same expression in clojurescript, and output the result to the browser console.

Claude's response:

The expression (+ 1 2 3) evaluates to 6 in ClojureScript as well, and the result has been logged to the browser console.The function returns nil because js/console.log doesn't return a value, but if you check your browser's developer console, you should see 6 printed there.

Success!

This is NOT required to use the Clojure MCP server.

IMPORTANT: if you have the following API keys set in yourenvironment, then ClojureMCP will make calls to them when you usethedispatch_agent,architect andcode_critique tools. Thesecalls will incur API charges.

There are a few MCP tools provided that are agents unto themselves and they need API keys to function.

To use the agent tools, you'll need API keys from one or more of these providers:

• GEMINI_API_KEY - For Google Gemini models

  • Get your API key at:https://makersuite.google.com/app/apikey
  • Used by:dispatch_agent,architect,code_critique

• OPENAI_API_KEY - For GPT models

  • Get your API key at:https://platform.openai.com/api-keys
  • Used by:dispatch_agent,architect,code_critique

• ANTHROPIC_API_KEY - For Claude models

  • Get your API key at:https://console.anthropic.com/
  • Used by:dispatch_agent

Option 1: Export in your shell

export ANTHROPIC_API_KEY="your-anthropic-api-key-here"export OPENAI_API_KEY="your-openai-api-key-here"export GEMINI_API_KEY="your-gemini-api-key-here"

Option 2: Add to your shell profile (.bashrc,.zshrc, etc.)

# Add these lines to your shell profileexport ANTHROPIC_API_KEY="your-anthropic-api-key-here"export OPENAI_API_KEY="your-openai-api-key-here"export GEMINI_API_KEY="your-gemini-api-key-here"

When setting up Claude Desktop, ensure it can access your environment variables by updating your config.

Personally Isource them right in bash command:

{"mcpServers": {"clojure-mcp": {"command":"/bin/sh","args": ["-c","source ~/.api_credentials.sh && PATH=/your/bin/path:$PATH && clojure -X:mcp"            ]        }    }}

Note: The agent tools will work with any available API key. You don't need all three - just set up the ones you have access to. The tools will automatically select from available models. For now the ANTHROPIC API is limited to the dispatch_agent.

This tool has a learning curve. You may in practice have to remindthe LLM to develop in the REPL. You may also have to remind the LLMto use theclojure_edit family of tools which have linters buildin to prevent unbalanced parens and the like.

The default tools included inmain.clj are organized by category to support different workflows:

• Collapsed View: Shows only function signatures for large Clojure files
• Pattern Matching: Usename_pattern to find functions by name,content_pattern to search content
• defmethod Support: Handles dispatch values like"area :rectangle" or vector dispatches
• Multi-language: Clojure files get smart features, other files show raw content

• Form-based Operations: Target functions by type and identifier, not text matching
• Multiple Operations: Replace, insert_before, insert_after
• Syntax Validation: Built-in linting prevents unbalanced parentheses
• defmethod Handling: Works with qualified names and dispatch values

• REPL Integration: Executes in the connected nREPL session
• Helper Functions: Built-in namespace and symbol exploration tools
• Multiple Expressions: Evaluates and partitions multiple expressions

• Configurable Execution: Can run over nREPL or locally based on config
• Session Isolation: When using nREPL mode, runs in separate session to prevent REPL interference
• Output Truncation: Consistent 8500 character limit with smart stderr/stdout allocation
• Path Security: Validates filesystem paths against allowed directories

• Autonomous Search: Handles complex, multi-step exploration tasks
• Read-only Access: Agents have read only tool access
• Detailed Results: Returns analysis and findings

• Persistent Workspace: Store structured data for planning and inter-tool communication
• Memory-Only by Default: Data is stored in memory only and lost when session ends (default behavior)
• Optional File Persistence: Enable to save data between sessions and server restarts
• Path-Based Operations: Useset_path,get_path,delete_path for precise data manipulation
• JSON Compatibility: Store any JSON-compatible data (objects, arrays, strings, numbers, booleans)

Default Behavior (Memory-Only):By default, the scratch pad operates in memory only. Data persists during the session but is lost when the MCP server stops.

Enabling Persistence:

Add to.clojure-mcp/config.edn:

{:scratch-pad-loadtrue; false by default:scratch-pad-file"workspace.edn"}; defaults to "scratch_pad.edn"

Persistence Details:

• Files are saved in.clojure-mcp/ directory within your project
• Changes are automatically saved when persistence is enabled
• Corrupted files are handled gracefully with error reporting

ClojureMCP is designed to be highly customizable. During the alpha phase, creating your own custom MCP server is the primary way to configure the system for your specific needs.

You can customize:

• Tools - Choose which tools to include, create new ones with multimethods or simple maps
• Prompts - Add project-specific prompts for your workflows
• Resources - Expose your documentation, configuration, and project information
• Tool Selection - Create read-only servers, development servers, or specialized configurations

The customization approach is both easy and empowering - you're essentially building your own personalized AI development companion.

📖Complete Customization Documentation

For a quick start:Creating Your Own Custom MCP Server - This is where most users should begin.

Using the -X invocation requires EDN values.

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.

:port 7888

Optional - The nREPL server host. Defaults to localhost if not specified.

:host "localhost" or:host "0.0.0.0"

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.

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.

Important: This option requires launchingclojure-mcp from your project directory (where yourdeps.edn orproject.clj is located). The nREPL server will be started in the current working directory. This is particularly useful for Claude Code and other command-line LLM clients where you want automatic nREPL startup without manual process management.

Note for Claude Desktop users: Claude Desktop does not start MCP servers from your project directory, so:start-nrepl-cmd will not work unless you also provide:project-dir as a command line argument pointing to your specific project. For example::project-dir '"/path/to/your/clojure/project"'. This limitation does not affect Claude Code or other CLI-based tools that you run from your project directory.

:start-nrepl-cmd ["lein" "repl" ":headless"] or:start-nrepl-cmd ["clojure" "-M:nrepl"]

Optional - Specify the location of a configuration file. Must be a path to an existing file.

:config-file "/path/to/config.edn"

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.

:project-dir "/path/to/your/clojure/project"

Optional - Specify the type of environment that we are connecting to over the nREPL connection. This overrides automatic detection. Valid options are:

• :clj for Clojure or ClojureScript
• :bb forBabashka - Native, fast starting Clojure interpreter for scripting
• :basilisp forBasilisp - A Clojure-compatible Lisp dialect targeting Python 3.9+
• :scittle forScittle - Execute ClojureScript directly from browser script tags

:nrepl-env-type :bb

# Basic usage with just portclojure -X:mcp :port 7888# With automatic nREPL server startup and port discovery# Perfect for Claude Code - run this from your project directoryclojure -X:mcp :start-nrepl-cmd'["lein" "repl" ":headless"]'# For Claude Code with Clojure projects (from project directory)clojure -X:mcp :start-nrepl-cmd'["clojure" "-M:nrepl"]'# Auto-start with explicit port (uses fixed port, no parsing)clojure -X:mcp :port 7888 :start-nrepl-cmd'["clojure" "-M:nrepl"]'# For Claude Desktop: must provide project-dir since it doesn't run from your projectclojure -X:mcp :start-nrepl-cmd'["lein" "repl" ":headless"]' :project-dir'"/path/to/your/clojure/project"'# With custom host and project directoryclojure -X:mcp :port 7888 :host'"0.0.0.0"' :project-dir'"/path/to/project"'# Using a custom config fileclojure -X:mcp :port 7888 :config-file'"/path/to/custom-config.edn"'# Specifying Babashka environmentclojure -X:mcp :port 7888 :nrepl-env-type :bb

Note: When using-X invocation, string values need to be properly quoted for the shell, hence'"value"' syntax for strings.

The Clojure MCP server supports minimal project-specific configurationthrough a.clojure-mcp/config.edn file in your project's rootdirectory. This configuration provides security controls andcustomization options for the MCP server.

Create a.clojure-mcp/config.edn file in your project root:

your-project/├── .clojure-mcp/│   └── config.edn├── src/├── deps.edn└── ...

Configuration is extensively documentedhere.

{:allowed-directories [".""src""test""resources""dev""/absolute/path/to/shared/code""../sibling-project"]:emacs-notifyfalse:write-file-guard:full-read:cljfmttrue:bash-over-nrepltrue:scratch-pad-loadfalse; Default: false:scratch-pad-file"scratch_pad.edn"}

Path Resolution:

• Relative paths (like"src","../other-project") are resolved relative to your project root
• Absolute paths (like"/home/user/shared") are used as-is
• The project root directory is automatically included in allowed directories

Security:

• Tools validate all file operations against the allowed directories
• Attempts to access files outside allowed directories will fail with an error
• This prevents accidental access to sensitive system files
• the Bash tool doesn't respect these boundaries so be wary

Default Behavior:

• Without a config file, only the project directory and its subdirectories are accessible
• The nREPL working directory is automatically added to allowed directories

{:allowed-directories [".""src""test""dev""resources""docs"]:write-file-guard:full-read:cljfmttrue:bash-over-nrepltrue:scratch-pad-loadfalse; Memory-only scratch pad:scratch-pad-file"scratch_pad.edn"}

{:allowed-directories [".""../shared-utils""../common-config""/home/user/reference-code"]:write-file-guard:partial-read:cljfmttrue:bash-over-nrepltrue:scratch-pad-loadtrue; Enable file persistence:scratch-pad-file"workspace.edn"}

{:allowed-directories ["src""test"]:write-file-guard:full-read:cljfmtfalse; Preserve original formatting:bash-over-nreplfalse; Use local execution only:scratch-pad-loadfalse; No persistence:scratch-pad-file"scratch_pad.edn"}

Note: Configuration is loaded when the MCP server starts. Restart the server after making configuration changes.

As mentioned above, thedispatch-agent-context configuration option allows you to add context aboutyour code before callingdispatch_agent. The default includes acode_index.txt file located inthe./.clojure-mcp/ folder in your project. This can be customized, of course.

In order to generate the code index, you will need to set up an alias for this purpose, then runclojure-mcp from the CLI.

{:aliases  {:index    {:deps {org.slf4j/slf4j-nop {:mvn/version"2.0.16"};; Required for stdio server            com.bhauman/clojure-mcp {:git/url"https://github.com/bhauman/clojure-mcp.git":git/tag"v0.1.11-alpha":git/sha"7739dba"}}:exec-fn clojure-mcp.code-indexer/map-project:exec-args {}}}}

Then run the indexer from the CLI:

# Basic usage with default settingsclojure -X:index# Customized code index generationclojure -X:index :dirs'["src" "lib"]' :include-teststrue :out-file'"my-index.txt"'

Of course, you will need to specify the name of the code index file when invokingdispatch_agent.

# Run testsclojure -X:test# Run specific testclojure -X:test :dirs'["test"]' :include'"repl_tools_test"'# Run linterclojure -M:lint

The core philosophy of this project is that:

1. Tiny steps with rich feedback lead to better quality code
2. REPL-driven development provides the highest quality feedback loop
3. Keeping humans in the loop ensures discernment and maintainable code

Eclipse Public License - v 2.0

Copyright (c) 2025 Bruce Hauman

This program and the accompanying materials are made available under theterms of the Eclipse Public License 2.0 which is available athttp://www.eclipse.org/legal/epl-2.0

• ✅Use freely for personal projects, internal business tools, and development
• ✅Modify and distribute - improvements and forks are welcome
• ✅Commercial use - businesses can use this commercially without restrictions
• ✅Flexible licensing - can be combined with proprietary code
• 📤Share improvements - source code must be made available when distributed