β οΈ Alpha Software - Work in ProgressThis project is in early development and rapidly evolving. While I've found it invaluable for working with Clojure projects and it has significantly improved my development workflow, expect breaking changes, rough edges, and incomplete documentation.
π€ Help Wanted! If you find this useful, please consider contributing:
- Report bugs and issues you encounter
- Suggest improvements or new features
- Submit pull requests for fixes or enhancements
- Share your configuration patterns and workflows
- Help improve documentation and examples
Your feedback and contributions will help make this tool better for the entire Clojure community!
A Model Context Protocol (MCP) server for Clojure that provides a complete set of tools to aid in the development of Clojure projects.
With Clojure MCP alone you can turn an LLM into a powerful Clojure REPL and coding assistant.
LLMs excel in the Clojure REPL: Current LLMs are unarguably fantastic Clojure REPL assistants that perform evaluations quickly and much more effectively than you can imagine. Ask anyone who has experienced this and they will tell you that the LLMs are performing much better in the Clojure REPL than they would have imagined. Additionally, we must remember that the form and maintainability of ephemeral code DOES NOT MATTER.
Buttery Smooth Clojure Editing: With current editing tools, LLMs still struggle with the parenthesis. Clojure MCP has a different take on editing that increases edit acceptance rates significantly. Clojure MCP lints code coming in, fixes parenthesis if possible, uses clj-rewrite to apply syntax aware patches, and then lints and formats the final result. This is a powerful editing pipeline that vastly outperforms when it comes to editing Clojure Code.
Together these two features along with a set of other Clojure aware tools create a new and unique LLM development experience that you probably should try at least once to understand how transformational it is.
This project implements an MCP server that connects AI models to a Clojure nREPL, and Specialized Clojure editing tools enabling a unique Clojure develop experience.
Clojure MCP provides a superset of the tools that Claude Code uses, so you can use it to work on Clojure without any other tools. I highly recommend using it with Claude Desktop to start. It's more attractive and there are no api charges!. Claude Desktop, also let's you have quick access to your own prompts and other resources provided by the clojure-mcp server. Having a stack of your own prompts available in a UI menu is very convenient.
If you use the built in Agent tools you will accumulate API charges.
- 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
- Emacs edit highlighting - alpha
For Clojurists an LLM assisted REPL is the killer application.
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 can control which tools are available to the model at any given moment so you can easily remove the ability to edit files and restrict the model to 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 and Claude 4 (sonnet or opus) (especially Claude 4 for best results)
- Gemini 2.5
- OpenAI o4-mini or o3
I highly recommend Claude 4 if you want to see long autonomous agentic action chains ...
The pattern-based structural editing tools require high model performance, so using one of these recommended models will significantly improve your experience.
The Clojure MCP tools are intentionally designed as a cohesive "action space" for Clojure development, rather than a collection of independent utilities. This design approach offers several key advantages:
- Smart file editing with automatic parenthesis balancing, linting, and formatting
- Structure-aware operations that understand Clojure syntax and semantics
- REPL-integrated development with stateful namespace management
The tools maintain state about file read/write operations to ensure safety:
- Tracks when files were last read vs. modified externally
- Prevents editing conflicts by validating file state before modifications
- Enables multiple sequential edits after a single read operation
- Uses canonical path resolution for reliable file identification
When tools work together as a system, they can:
- Share context and state for more intelligent behavior
- Provide consistent interfaces and error handling
- Optimize the overall development workflow
While you can use these tools alongside Claude Code and other code assistants with their own tooling, we recommend trying the Clojure MCP tools independently first to experience their full capabilities. Here's why:
Potential Conflicts:
- Both systems track file read/write state independently, which can cause confusion
- Overlapping tool functionality may lead to inconsistent behavior
- Mixed toolsets can dilute the optimized workflow experience
Getting the Full Benefits:
- Experience the curated Clojure development workflow as intended
- Understand how the tools complement each other
- Appreciate the Clojure-specific enhancements and safety features
- Develop familiarity with the integrated approach before mixing systems
Once you're comfortable with the Clojure MCP toolset, you can make informed decisions about whether to use it exclusively or integrate it with other code assistants and development tools based on your specific workflow needs.
- Clojure (1.11 or later)
- Java (JDK 11 or later)
- Claude Desktop (for the best experience)
Set it up as git dep in a local deps.edn
or global .clojure/deps.edn
like:
{:aliases
{:mcp
{:deps {org.slf4j/slf4j-nop {:mvn/version "2.0.16"}
com.bhauman/clojure-mcp {:git/url "https://github.com/bhauman/clojure-mcp.git"
:git/tag "v0.1.1-alpha"
:git/sha "0fcac09"}}
:exec-fn clojure-mcp.main/start-mcp-server
:exec-args {:port 7888}}}}
Finding the latest SHA: Visit https://github.com/bhauman/clojure-mcp/commits/main to get the latest commit SHA, or clone the repo and run
git log --oneline -1
to see the latest commit.
or from a local clone of clojure-mcp
{:aliases
{:mcp
{:deps {org.slf4j/slf4j-nop {:mvn/version "2.0.16"}
com.bhauman/clojure-mcp {:local/root "~/workspace/clojure-mcp"}}
:exec-fn clojure-mcp.main/start-mcp-server
:exec-args {:port 7888}}}}
Local clone path: Replace
~/workspace/clojure-mcp
with the actual path where you cloned the repository (e.g.,~/dev/clojure-mcp
,/Users/username/projects/clojure-mcp
, etc.)
IMPORTANT NOTE: the mcp server can run in any directory and DOES NOT have to run from your project directory. The mcp server looks to the nREPL connection for context. The root directory of the project that is running the nREPL server becomes the root directory of all the mcp tool invocations. Currently the nREPL must run on the same machine as the MCP server as there is an assumption of a shared file system between the nREPL server and the MCP server.
ANOTHER IMPORTANT NOTE:
clojure-mcp
should not run as part of your project and your project dependencies should not mingle with clojure-mcp. It should run separately, with its own set of deps. So if you include it in your projectsdeps.edn
it should not use:extra-deps
in its alias is should always use:deps
In the Clojure project where you want AI assistance, add an nREPL connection.
{:aliases {
;; nREPL server for AI to connect to
:nrepl {:extra-paths ["test"]
:extra-deps {nrepl/nrepl {:mvn/version "1.3.1"}}
:jvm-opts ["-Djdk.attach.allowAttachSelf"]
:main-opts ["-m" "nrepl.cmdline" "--port" "7888"]}}}
Edit your Claude Desktop configuration file:
- Location:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"clojure-mcp": {
"command": "/bin/sh",
"args": [
"-c",
"cd ~/workspace/clojure-mcp && PATH=/opt/homebrew/bin:$PATH && clojure -X:mcp :port 7888"
]
}
}
}
Replace these paths:
~/workspace/clojure-mcp
β Your clojure-mcp location (same as Step 1)/opt/homebrew/bin
β Your system's binary path:- Homebrew (Intel Mac):
/usr/local/bin
- Homebrew (Apple Silicon):
/opt/homebrew/bin
- Nix:
/home/username/.nix-profile/bin
or/nix/var/nix/profiles/default/bin
- System default: Often
/usr/bin:/usr/local/bin
works
- Homebrew (Intel Mac):
-
Start nREPL in your target project:
cd /path/to/your/project clojure -M:nrepl
You should see:
nREPL server started on port 7888...
-
Start or Restart Claude Desktop (required after config changes)
-
Verify connection: In Claude Desktop, click the
+
button in the chat area. You should see "Add from clojure-mcp" in the menu.
In Claude Desktop click the +
tools and optionally add
- resource
PROJECT_SUMMARY.md
- (have the LLM create this) see below - resource
Clojure Project Info
- which introspects the nREPL connected project - resource
LLM_CODE_STYLE.md
- Which is your personal coding style instructions (copy the one in this repo) - prompt
clojure_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 to interactively design a solution. You can ask Claude to "propose" a solution 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 are absolutely 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.
This project includes a workflow for maintaining an LLM-friendly PROJECT_SUMMARY.md
that helps assistants quickly understand the codebase structure.
-
Creating the Summary: To generate or update the PROJECT_SUMMARY.md file, use the MCP prompt in the
+
>clojure-mcp
menucreate-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
-
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
-
Keeping It Updated: At the end of a productive session where new features or components were added:
- Invoke the
create-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
- Invoke the
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 enable
conversation continuity across chat sessions using the scratch_pad
tool. This will be stored in memory. Things stored in the scratch_pad
are not persisted to disk (yet).
The system uses two complementary prompts:
-
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 optional
chat_session_key
parameter (defaults to"chat_session_summary"
)
-
chat-session-resume
: Restores context from a previous conversation- Reads the PROJECT_SUMMARY.md file
- Calls
clojure_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 optional
chat_session_key
parameter (defaults to"chat_session_summary"
)
Ending a Session:
- At the end of a productive conversation, invoke the
chat-session-summarize
prompt - The assistant will store a comprehensive summary in the scratch pad
- This summary persists across sessions thanks to the scratch pad's global state
Starting a New Session:
- When continuing work, invoke the
chat-session-resume
prompt - The assistant will load all relevant context and provide a brief summary
- You can then continue where you left off with full context
You can maintain multiple parallel conversation contexts by using custom keys:
# For feature development
chat-session-summarize with key "feature-auth-system"
# For bug fixing
chat-session-summarize with key "debug-memory-leak"
# Resume specific context
chat-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.
This is NOT required to use the Clojure MCP server.
IMPORTANT: if you have the following API keys set in your environment, then ClojureMCP will make calls to them when you use the
dispatch_agent
,architect
andcode_critique
tools. These calls 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 profile
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"
When setting up Claude Desktop, ensure it can access your environment variables by updating your config.
{
"mcpServers": {
"clojure-mcp": {
"command": "/bin/sh",
"args": [
"-c",
"cd /path/to/your/mcp-server/home && PATH=/your/bin/path:$PATH && clojure -X:mcp"
],
"env": {
"ANTHROPIC_API_KEY": "$ANTHROPIC_API_KEY",
"OPENAI_API_KEY": "$OPENAI_API_KEY",
"GEMINI_API_KEY": "$GEMINI_API_KEY"
}
}
}
}
Personally I source
them right in bash command:
{
"mcpServers": {
"clojure-mcp": {
"command": "/bin/sh",
"args": [
"-c",
"source ~/.api_credentials.sh && cd /path/to/your/mcp-server/home && 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 displatch_agent.
This tool has a learning curve. You may in practice have to remind the LLM to develop in the REPL. You may also have to remind the LLM to use the
clojure_edit
family of tools which have linters build in to prevent unbalanced parens and the like.
The default tools included in main.clj
are organized by category to support different workflows:
Tool Name | Description | Example Usage |
---|---|---|
LS |
Returns a recursive tree view of files and directories | Exploring project structure |
read_file |
Smart file reader with pattern-based exploration for Clojure files | Reading files with collapsed view, pattern matching |
fs_grep |
Fast content search using regular expressions | Finding files containing specific patterns |
glob_files |
Pattern-based file finding | Finding files by name patterns like *.clj |
think |
Log thoughts for complex reasoning and brainstorming | Planning approaches, organizing thoughts |
Tool Name | Description | Example Usage |
---|---|---|
clojure_eval |
Evaluates Clojure code in the current namespace | Testing expressions like (+ 1 2) |
bash |
Execute shell commands on the host system | Running tests, git commands, file operations |
Tool Name | Description | Example Usage |
---|---|---|
clojure_edit |
Structure-aware editing of Clojure forms | Replacing/inserting functions, handling defmethod |
clojure_edit_replace_sexp |
Modify expressions within functions | Changing specific s-expressions |
file_edit |
Edit files by replacing text strings | Simple text replacements |
file_write |
Write complete files with safety checks | Creating new files, overwriting with validation |
Tool Name | Description | Example Usage |
---|---|---|
dispatch_agent |
Launch agents with read-only tools for complex searches | Multi-step file exploration and analysis |
architect |
Technical planning and implementation guidance | System design, architecture decisions |
Tool Name | Description | Example Usage |
---|---|---|
code_critique |
Interactive code review and improvement suggestions | Iterative code quality improvement |
- Collapsed View: Shows only function signatures for large Clojure files
- Pattern Matching: Use
name_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
- Autonomous Search: Handles complex, multi-step exploration tasks
- Read-only Access: Agents have read only tool access
- Detailed Results: Returns analysis and findings
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.
The Clojure MCP server supports minimal project-specific configuration
through a .clojure-mcp/config.edn
file in your project's root
directory. This configuration provides security controls and
customization 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
βββ ...
Controls which directories the MCP tools can access for security. Paths can be relative (resolved from project root) or absolute.
Boolean flag to enable Emacs integration notifications.
Prerequisites for Emacs Integration:
emacsclient
must be available in your system PATH- Emacs server must be running (start with
M-x server-start
or add(server-start)
to your init file) - The integration allows the MCP server to communicate with your Emacs editor for enhanced development workflows
{:allowed-directories ["."
"src"
"test"
"resources"
"dev"
"/absolute/path/to/shared/code"
"../sibling-project"]
:emacs-notify false}
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"]
:emacs-notify false}
{:allowed-directories ["."
"../shared-utils"
"../common-config"
"/home/user/reference-code"]
:emacs-notify false}
{:allowed-directories ["src"
"test"]
:emacs-notify false}
Note: Configuration is loaded when the MCP server starts. Restart the server after making configuration changes.
- Express the problem - Clearly state what you want to solve
- Develop in the REPL - Work through solutions incrementally
- Validate step-by-step - Test each expression before moving on
- Save to files - When the solution is working, save it properly
- 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
# Run tests
clojure -X:test
# Run specific test
clojure -X:test :dirs '["test"]' :include '"repl_tools_test"'
# Run linter
clojure -M:lint
The core philosophy of this project is that:
- Tiny steps with rich feedback lead to better quality code
- REPL-driven development provides the highest quality feedback loop
- Keeping humans in the loop ensures discernment and maintainable code
GNU Affero General Public License v3.0
Copyright (c) 2025 Bruce Hauman
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.
- β Use freely for personal projects, internal business tools, and development
- β Modify and distribute - improvements and forks are welcome
- β Commercial use - businesses can use this internally without restrictions
β οΈ Network copyleft - if you offer this as a service to others, you must open source your entire service stack- π€ Share improvements - modifications must be shared under the same license
This license ensures the project remains open source while preventing commercial exploitation without contribution back to the community.