Clojure Nrepl

🚀 nREPL MCP Server

A server designed for Model Context Protocol (MCP) clients, such as Claude Desktop or CLine in VSCode. This server can be used with any LLM (when used via CLine). It can interact with a running Clojure nREPL instance, enabling useful features like evaluating Clojure code in a specified or current namespace and inspecting namespaces.

🚀 Quick Start

The nREPL MCP Server is a powerful tool for interacting with Clojure nREPL instances through MCP clients. Here's a brief overview of what it can do and how to get started.

✨ Features

• Connect to a running nREPL server by specifying the host and port.
• Evaluate Clojure code in a specified or the current namespace.
• List project namespaces using tools.namespace.
• Retrieve the nREPL connection status, including host, port, and session details.
• Inspect public variables to get metadata (such as docstrings and values) from any Clojure namespace.

📦 Installation

Installation in CLine (VSCode) or Claude Desktop

To use this server with CLine or Claude Desktop, follow these steps:

1. Open CLine in VSCode or Claude Desktop.
2. Navigate to MCP settings.
3. Add a new MCP server with the following configuration:

{
    "mcpServers": {
        "nrepl-mcp-server": {
            "command": "npx",
            "args": [
                "nrepl-mcp-server"
            ],
            "disabled": false,
            "autoApprove": []
        }
    }
}

4. Save and restart the client to apply the changes. This allows the client to communicate with the nREPL MCP server via standard input/output.

Installation via npx

To quickly run the server without cloning the repository:

npx nrepl-mcp-server

Manual Installation

1. Clone the repository
2. Install dependencies

npm install

3. Build the project (convert TypeScript to JavaScript)

npm run build

4. Run the server

• Production mode: Run from the compiled output.

npm start

• Development mode: Use ts-node for live changes.

npm run dev

This starts the server, listening for MCP requests on standard input/output. The MCP client will start the server for you.

💻 Usage Examples

Connecting to nREPL

Allows establishing a connection to an nREPL server by specifying the host and port.

Evaluating Clojure Code

Execute any Clojure expression, either in the default namespace or a specified namespace.

Retrieving Namespace Information

List all namespaces in the project directory using tools.namespace.

Inspecting Public Variables

Get metadata and current values of all public variables in a specified namespace.

Retrieving nREPL Connection Status

Provide detailed information about the current nREPL connection, including host, port, session ID, and the last error (if any).

📚 Documentation

nrepl://status

Provide information about the current nREPL connection, including:

• Host and port
• Connection status
• Active session ID

nrepl://namespaces

List all namespaces detected in the project directory.

🤝 Contribution

Contributions are welcome! If you have any feature suggestions or error reports, please open an issue or a pull request.

📄 License

This project is licensed under the MIT License. You can freely modify and distribute it according to its terms.