The nREPL MCP Server enables interaction with a running Clojure nREPL instance via the Model Context Protocol (MCP). With this server, you can:
Connect to an nREPL server by specifying host and port
Evaluate arbitrary Clojure expressions in a specific namespace or the current one
List all namespaces in the current project directory using tools.namespace
Inspect public vars in any namespace, including their metadata, docstrings, and values
Manage nREPL sessions for operations like loading files and defining functions
Retrieve connection status details including host, port, session ID, and any errors
Enables interaction with a running Clojure nREPL instance, allowing evaluation of Clojure code, namespace inspection, and retrieving metadata for public vars in Clojure namespaces
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@nREPL MCP Server evaluate (+ 1 2 3) in the user namespace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
Related MCP server: Emacs MCP Tools
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.
npxTo quickly run the server without cloning the repository:
npx nrepl-mcp-serverClone the repository
Install dependencies
npm installBuild the project (transpiles TypeScript to JavaScript)
npm run buildRun the server
Production Mode: Runs from compiled output.
npm startDevelopment Mode: Uses ts-node for live changes.
npm run devThis starts the server, listening on STDIO for MCP requests. Mcp client will start the server for you.
Allows establishing a connection to an nREPL server by specifying a host and port.
Executes arbitrary Clojure expressions in either the default namespace or a specified namespace.
Lists all namespaces in the current project directory using tools.namespace.
Fetches metadata and current values for all public vars in a specified namespace.
Provides details on the current nREPL connection, including host, port, session ID, and last error (if any).
nrepl://statusProvides information about the current nREPL connection, including:
Host and port
Connection status
Active session ID
nrepl://namespacesLists all namespaces detected in the project directory.
Contributions are welcome! If you have feature suggestions or bug reports, please open an issue or pull request.
This project is licensed under the MIT License. Feel free to modify and distribute according to its terms.
Connect to an nREPL server. Example: (connect {:host "localhost" :port 1234})
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | nREPL server host | |
| port | Yes | nREPL server port |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Connect') but does not disclose behavioral traits such as whether this is a one-time or persistent connection, error handling, authentication needs, or what happens upon successful connection. The example adds minimal context but leaves key operational details unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, with the first sentence stating the purpose clearly and the second providing a practical example. Every sentence earns its place by reinforcing understanding without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a connection tool with no annotations and no output schema, the description is incomplete. It lacks information about what the tool returns upon success or failure, connection persistence, or error conditions, which are critical for an agent to use it effectively in a workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with both parameters ('host' and 'port') well-documented in the schema. The description adds an example that illustrates parameter usage but does not provide additional semantic meaning beyond what the schema already specifies, such as format constraints or default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Connect to') and target resource ('an nREPL server'), with an example that reinforces the purpose. It distinguishes itself from sibling tools like 'eval_form' and 'get_ns_vars' by focusing on establishing a connection rather than evaluating code or retrieving namespace variables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to establish a connection to an nREPL server, but it does not provide explicit guidance on when to use this tool versus alternatives or any prerequisites. The example suggests typical usage scenarios but lacks context about timing or dependencies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate Clojure code in a specific namespace or the current one. Examples:
Define and call a function: {"code": "(defn greet [name] (str "Hello, " name "!"))(greet "World"))"}
Reload code: {"code": "(clj-reload.core/reload)"}
Evaluate in a specific namespace: {"code": "(clojure.repl.deps/sync-deps)", "ns": "user"}
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Clojure code to evaluate | |
| ns | No | Optional namespace to evaluate in. Changes persist for subsequent evaluations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that namespace changes 'persist for subsequent evaluations,' which is useful behavioral context. However, it lacks details on error handling, side effects, or performance implications, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with a clear purpose statement followed by specific examples. Each sentence earns its place by illustrating use cases without unnecessary elaboration, making it efficient and easy to understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (evaluating code with potential side effects), no annotations, and no output schema, the description is moderately complete. It covers purpose and usage examples but lacks details on return values, error formats, or security considerations, which are important for a code evaluation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('code' and 'ns'). The description adds value by providing examples that illustrate parameter usage, such as showing code snippets and namespace context, but does not add new semantic details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Evaluate Clojure code in a specific namespace or the current one.' It specifies the verb ('evaluate'), resource ('Clojure code'), and scope ('specific namespace or the current one'), distinguishing it from sibling tools like 'connect' and 'get_ns_vars' which likely serve different functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage through examples, such as defining functions, reloading code, and evaluating in a namespace. However, it does not explicitly state when to use this tool versus alternatives like 'get_ns_vars' or any exclusions, leaving some ambiguity in tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all public vars (functions, values) in a namespace with their metadata and current values. Example:
List main namespace vars: (get_ns_vars {:ns "main"}) Returns a map where keys are var names and values contain:
:meta - Metadata including :doc string, :line number, :file path
:value - Current value of the var
| Name | Required | Description | Default |
|---|---|---|---|
| ns | Yes | Namespace to inspect |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return format (a map with keys as var names and values containing metadata and current values), which is helpful, but doesn't cover aspects like permissions needed, rate limits, error conditions, or whether it's a read-only operation (though 'Get' implies reading).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose in the first sentence. The example and return format details are useful but could be slightly more streamlined. Overall, it's efficient with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (1 parameter, no output schema, no annotations), the description is somewhat complete but has gaps. It explains the return structure well, but lacks information on usage context, error handling, and behavioral traits like safety or performance considerations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single parameter 'ns' as 'Namespace to inspect'. The description adds an example usage with {:ns "main"} but doesn't provide additional semantic context beyond what the schema states, such as namespace format or scope limitations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'all public vars (functions, values) in a namespace with their metadata and current values', which is specific and comprehensive. It distinguishes from sibling tools (connect, eval_form) by focusing on namespace inspection rather than connection or evaluation operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It includes an example usage but doesn't mention prerequisites, constraints, or compare it to sibling tools like eval_form, which might also interact with namespace variables.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: connect establishes a connection, eval_form evaluates code, and get_ns_vars inspects namespace variables. There is no overlap or ambiguity between these three functions.
The naming follows a consistent snake_case pattern (connect, eval_form, get_ns_vars), with all tools using descriptive verb-noun combinations. The minor deviation is that 'connect' is a single verb while others are compound, but this is reasonable given its action.
With only 3 tools, the set feels thin for an nREPL server, which typically involves more operations like disconnecting, listing sessions, or handling side effects. However, it covers basic connectivity, evaluation, and inspection, which are core functions.
The tool surface has significant gaps for an nREPL server: there is no way to disconnect or manage sessions, handle errors or interrupts, load files, or perform other common REPL operations. This limits agents to basic tasks and may cause failures in more complex workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/JohanCodinha/nrepl-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
