nrepl MCP Server

Use This MCP server To

Evaluate Clojure code dynamically within an MCP client Inspect and list namespaces in a Clojure project Retrieve and monitor nREPL connection status and session info Explore public vars and their metadata in Clojure namespaces Integrate Clojure REPL capabilities into AI-assisted coding environments

README

nREPL MCP Server

A Model Context Protocol (MCP) server designed for MCP clients, such as Claude Desktop or CLine in VSCode. This server can be used with any LLM when used with CLine. This server enables interaction with a running Clojure nREPL instance, allowing evaluation of Clojure code, namespace inspection, and other utilities via MCP.

Features

Connect to a running nREPL server by specifying host and port.
Evaluate Clojure code in a given namespace or the current one.
List project namespaces using tools.namespace.
Retrieve nREPL connection status, including host, port, and session details.
Inspect public vars in any Clojure namespace, displaying metadata such as docstrings and values.

Installation & Setup

Installing in CLine (VSCode) or Claude Desktop

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

Open CLine in VSCode or Claude Desktop.
Navigate to the MCP Settings.

Add a new MCP server with the following configuration:

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

Save and restart the client to apply changes.

This will allow the client to communicate with the nREPL MCP server via standard input/output.

Install via `npx`

To quickly run the server without cloning the repository:

npx nrepl-mcp-server

Manual Installation

Clone the repository
Install dependencies
```
npm install
```
Build the project (transpiles TypeScript to JavaScript)
```
npm run build
```
Run the server
- Production Mode: Runs from compiled output.
```
npm start
```
- Development Mode: Uses ts-node for live changes.
```
npm run dev
```

This starts the server, listening on STDIO for MCP requests. Mcp client will start the server for you.

Actions

Connecting to nREPL

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

Evaluating Clojure Code

Executes arbitrary Clojure expressions in either the default namespace or a specified namespace.

Retrieving Namespace Information

Lists all namespaces in the current project directory using tools.namespace.

Inspecting Public Vars

Fetches metadata and current values for all public vars in a specified namespace.

Fetching nREPL Connection Status

Provides details on the current nREPL connection, including host, port, session ID, and last error (if any).

Resources

`nrepl://status`

Provides information about the current nREPL connection, including:

Host and port
Connection status
Active session ID

`nrepl://namespaces`

Lists all namespaces detected in the project directory.

Contributing

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

License

This project is licensed under the MIT License. Feel free to modify and distribute according to its terms.

nrepl-mcp-server FAQ

How do I connect the nrepl-mcp-server to my running nREPL instance?

Specify the host and port of your running nREPL server in the nrepl-mcp-server configuration to establish a connection.

Can I evaluate Clojure code in any namespace using this server?

Yes, you can evaluate code in a specified namespace or the current one via the MCP interface.

What metadata can I retrieve about public vars in namespaces?

You can access docstrings, values, and other metadata for public vars in any inspected namespace.

Is this server compatible with multiple MCP clients?

Yes, it works with MCP clients like Claude Desktop and CLine in VSCode, supporting any LLM through MCP.

How do I list all namespaces in my Clojure project?

The server uses tools.namespace to list all project namespaces accessible via the MCP client.

What information does the nREPL connection status provide?

It includes host, port, session details, and connection health for your nREPL instance.

Can this server be used with LLMs other than Claude Desktop?

Yes, it supports any LLM integrated through MCP, including OpenAI, Claude, and Gemini.

How do I install the nrepl-mcp-server for use in VSCode?

Follow the installation instructions for CLine in VSCode or Claude Desktop as detailed in the GitHub README.