Gerbil

You can connect an MCP client to this Gerbil-MCP server to execute Gerbil Scheme expressions, inspect modules, expand macros, manage packages, run tests, and maintain persistent REPL sessions against a real Gerbil runtime. This enables AI assistants to interact with Gerbil live, perform code analysis, and scaffold projects with accurate runtime behavior.

How to use

You will run the MCP server locally and connect an MCP client such as Claude Code or GitHub Copilot to it via standard input/output. The server exposes a set of tools that let you evaluate Gerbil expressions, inspect module exports, check syntax, expand macros, trace macro expansion, manage REPL sessions, run tests, inspect FFI bindings, and perform project-related tasks. You can execute these actions one-off for ad hoc analysis or incorporate them into your editor workflow to get Gerbil-aware guidance and results.

How to install

Prerequisites: You need Node.js version 18 or newer and Gerbil Scheme installed with gxi, gxc, and gxpkg available (tested with v0.19+). Then follow these steps to install the MCP server and prepare to run it.

# 1) Clone the MCP server repository
git clone https://github.com/ober/gerbil-mcp.git

# 2) Enter the project directory
cd gerbil-mcp

# 3) Install dependencies
npm install

# 4) Build the project
npm run build

Configuration overview

The server is intended to be run as a local stdio MCP server. You start the server via Node and pass the built entry point, typically dist/index.js, to the node executable. An environment variable is used to locate the Gerbil gxi binary.

# Example start command (replace with your absolute path):
node /absolute/path/to/gerbil-mcp/dist/index.js

Environment variables you will need

You should provide the path to the Gerbil Xi tool and related binaries when starting the MCP server so it can drive Gerbil correctly.

GERBIL_MCP_GXI_PATH=/opt/gerbil/bin/gxi
GERBIL_MCP_GXC_PATH=/opt/gerbil/bin/gxc
GERBIL_MCP_GXPKG_PATH=/opt/gerbil/bin/gxpkg
GERBIL_HOME=/opt/gerbil

Available tools

gerbil_eval

Evaluate a Gerbil Scheme expression and return the result. You can import modules first.

gerbil_module_exports

List all exported symbols from a Gerbil module.

gerbil_check_syntax

Validate Gerbil code without evaluating it using the expander.

gerbil_expand_macro

Show the core-expanded form of a Gerbil expression.

gerbil_apropos

Search for symbols matching a pattern across namespaces.

gerbil_list_std_modules

List available standard library modules by scanning the Gerbil installation.

gerbil_function_signature

Get arity and type information for exports in a module.

gerbil_module_deps

Show what modules a given module imports, with optional transitive resolution.

gerbil_load_file

Read a Gerbil source file and extract its top-level definitions without executing.

gerbil_doc

Look up comprehensive information about a symbol, including type and arity.

gerbil_compile_check

Run the Gerbil compiler in expand-only mode to catch compilation errors.

gerbil_trace_macro

Show step-by-step macro expansion for a Gerbil expression.

gerbil_repl_session

Manage persistent Gerbil REPL sessions with state that persists across evaluations.

gerbil_run_tests

Run a Gerbil test file using the :std/test framework and return structured results.

gerbil_ffi_inspect

Inspect a Gerbil module's FFI bindings, classifying constants, C-style functions, and wrappers.

gerbil_class_info

Inspect a Gerbil defclass/defstruct type descriptor.

gerbil_find_definition

Find where a Gerbil symbol is defined, returning qualified name and source info.

gerbil_build_project

Build or clean a Gerbil project directory using gxpkg.

gerbil_package_info

List installed Gerbil packages, search the package directory, or show metadata.

gerbil_format

Pretty-print Gerbil Scheme expressions using Gambit pretty-print.

gerbil_benchmark

Time a Gerbil expression with detailed performance statistics.

gerbil_error_hierarchy

Show the full Gerbil exception/error type hierarchy as a tree.

gerbil_version

Report Gerbil and Gambit versions and installation details.

gerbil_scaffold

Create a new Gerbil project from a template using gxpkg.

gerbil_package_manage

Install, update, or uninstall Gerbil packages.

gerbil_find_callers

Find all files that reference a given symbol across a directory.

gerbil_suggest_imports

Identify which standard library module exports a given symbol.