Overview

Lisply MCP Server is middleware that implements a lightweight Model Context Protocol (MCP) bridge for Lisp-style development and runtime environments. It lets MCP-capable AI agents (for example, Claude Desktop or other MCP clients) connect to Lisp REPLs and perform programmatic operations — evaluate expressions, compile and load files, run tests, query symbols, and more — using a small, consistent protocol called “Lisply”.

The server is intended for developers who want to combine large language model (LLM) assistance with symbolic Lisp workflows: editing, compiling, running, and inspecting Lisp code from an LLM-enabled client. By exposing Lisp operations as MCP tools, Lisply makes it straightforward to integrate AI-assisted coding, debugging, and automation into Lisp-centered projects.

Repository: https://github.com/gornskew/lisply-mcp

Features

MCP middleware exposing Lisp REPL functionality as MCP tools.
Works with Common Lisp implementations running locally or as containers.
Tool names are automatically namespaced per MCP server instance to avoid conflicts when you run multiple Lisply servers.
Support for evaluating expressions, compiling/loading files, running tests, and describing symbols/projects.
Designed to be lightweight and easy to launch via Node + Docker.
Example wrapper script (scripts/mcp-wrapper.js) for launching as an MCP server process.

Installation / Configuration

Prerequisites:

Node.js 18+ (or compatible)
Docker Engine 20+ (if you plan to run the included Lisp backends in containers)

Quick clone and start (minimal steps):

Clone the repo:

git clone https://github.com/gornskew/lisply-mcp.git
cd lisply-mcp

Start the default containerized backend (recommended via Docker Compose or follow the skewed-emacs “Containerized Runnings” section for an example setup). Note: the current branch may be unstable for auto-starting containers; the skewed-emacs docs provide a reliable containerized setup.
Configure your MCP-capable client to launch the wrapper script. Example for Claude Desktop (Windows host):

Replace /path/to/cloned/ with the absolute path to your clone.

JSON example (Windows or macOS path):

{
  "mcpServers": {
    "gendl-ccl": {
      "command": "node",
      "args": [
        "/path/to/cloned/lisply-mcp/scripts/mcp-wrapper.js",
        "--server-name", "gendl-ccl",
        "--http-port", "9080"
      ]
    }
  }
}

WSL example (if Claude Desktop runs on Windows but you want to run the wrapper inside WSL):

{
  "mcpServers": {
    "gendl-ccl": {
      "command": "wsl",
      "args": [
        "node /home/you/lisply-mcp/scripts/mcp-wrapper.js --server-name gendl-ccl --http-port 9080"
      ]
    }
  }
}

Notes:

Each MCP server instance runs independently; tool names get prefixed with the server name (e.g., gendl-ccl__lisp_eval).
You can expose/ mount your host project directories into the Lisp container so that file compile/load operations work against your workspace.

Available Tools / Resources

Lisply-MCP exposes a small set of tools to interact with the Lisp backend. Names shown without server prefix — actual tool names are prefixed by the MCP server name you configure.

Tool name (unprefixed)	Purpose
lisp_eval	Evaluate an arbitrary Lisp expression and return result and/or printed output.
lisp_compile	Compile a file or source form; report compile results, warnings, and errors.
lisp_load	Load a compiled file or source file into the running image.
lisp_describe	Return information about a symbol, package, or project (docstrings, type, signature).
lisp_run_tests	Run test suites or specific test cases and report results.

The exact tool set and parameters may vary by Lisply backend. Consult the running server’s /tools endpoint (if available) or the wrapper script docs in the repo for the authoritative list.

Use Cases

LLM-assisted iterative development: Ask an LLM to generate a function, compile it in the Lisp image, run unit tests, and refine code until tests pass.
Code inspection and documentation: Query symbol descriptions, docstrings, and package contents from the running Lisp environment to augment LLM responses with exact runtime facts.
Experimental automation: Drive Lisp-based CAD, KBE (Knowledge Based Engineering), or domain-specific automation flows by invoking Lisp operations from an MCP-capable agent.
Multi-environment workflows: Run several Lisply servers (e.g., SBCL, CCL, siloed project images) and let the LLM target a specific environment via server-prefixed tools.

Example prompt to test connectivity from your LLM agent: “Evaluate (+ 1 2 3) using the gendl-ccl__lisp_eval tool and return the numeric result.” Expected: the tool is invoked and the LLM reports 6.

Notes & Troubleshooting

Branch stability: Some branches in the repo may not auto-start containers reliably. If you experience container startup issues, follow the Containerized Runnings guide in the skewed-emacs README (linked in the repo) for a tested Docker Compose setup.
Ports: Ensure the chosen HTTP ports (e.g., 7080, 9080, 9090) are free and properly forwarded if running inside WSL or a VM.
File mounts: To work with your project files from the Lisp backend, mount your host project directory into the container image and point compile/load operations to the mounted path.
Multiple servers: When running multiple Lisply servers, use distinct –server-name values so tools are automatically namespaced and do not conflict.

For more details and updates, see the repository: https://github.com/gornskew/lisply-mcp

Lisply MCP Server for Lisp-Speaking Backend Services