nrepl

This MCP server provides an interface to a running Clojure nREPL instance via MCP. It lets you connect to an nREPL host and port, evaluate Clojure code in either the default namespace or a specified one, inspect public vars and metadata, and query the current connection status. The server is designed to work with MCP clients like Claude Desktop or CLine, allowing these clients to send MCP requests that are translated into nREPL operations and returned in MCP-compatible responses. Typical workflows include evaluating small snippets of Clojure, loading project namespaces, and exploring public vars for documentation or debugging purposes.

To use the server, run it via npx or install it locally, then configure your MCP client to connect over standard input/output. Once connected, you can issue actions such as connecting to an nREPL host:port, evaluating code in a namespace, listing namespaces with tools.namespace, and fetching metadata for public vars. The server exposes helpful endpoints like status and namespaces so you can monitor the current nREPL connection and available namespaces within your project.

Prerequisites:

• Node.js and npm installed on your machine
• Access to a running nREPL server if you want to connect to an existing nREPL instance

Option A: Quick start with npx (no local clone required)

1. Open a terminal.
2. Run:

npx nrepl-mcp-server

3. The server starts and listens on STDIO for MCP requests. Use your MCP client to connect and start issuing commands.

Option B: Manual installation from source

1. Clone the repository:

git clone https://github.com/your-org/johancodinha-nrepl-mcp-server.git
cd johancodinha-nrepl-mcp-server

2. Install dependencies:

npm install

3. Build the project (transpile TypeScript to JavaScript) if applicable:

npm run build

4. Run the server:

• Production mode:

npm start

• Development mode (for live changes):

npm run dev

5. The server will listen on STDIO for MCP requests. Use an MCP client to interact with the nREPL instance.

Tips and notes:

• The server is designed to connect to an existing nREPL instance by providing host and port through MCP actions. Ensure the nREPL server is accessible from the machine running the MCP server.
• You can inspect namespaces and public vars to discover available code and documentation while debugging or developing interactively.
• If you encounter connection issues, verify that your firewall allows the host/port combo and that your nREPL is configured to accept external connections.
• Some MCP clients may require explicit initialization or a short delay after establishing the connection before performing evaluation or inspection actions.
• The README references standard MCP actions like connecting, evaluating code, listing namespaces, and inspecting vars; consult the client’s documentation for the exact MCP payloads and response formats if you plan to automate interactions.