Gerbil MCP Server

gerbil-mcp

An MCP (Model Context Protocol) server that gives AI assistants live access to a Gerbil Scheme environment. It lets Claude (or any MCP client) evaluate expressions, inspect module exports, check syntax, expand macros, compile-check code, trace macro expansion step by step, maintain persistent REPL sessions, profile function performance, analyze heap memory usage, trace call counts, visualize call graphs, manage packages, scaffold projects and test files, generate module stubs, build projects with structured diagnostics, find symbol references, and suggest imports — all against a real Gerbil runtime instead of guessing from training data.

The server also provides MCP resources for browsing the cookbook recipe library, prompts for common Gerbil workflows, and tool annotations (readOnlyHint/idempotentHint) so clients can make informed decisions about tool safety.

Prerequisites

• Node.js >= 18
• Gerbil Scheme installed with gxi, gxc, and gxpkg available (tested with v0.19+)

Install

git clone https://github.com/ober/gerbil-mcp.git
cd gerbil-mcp
npm install
npm run build

Configure

Claude Code

Add the MCP server using the CLI (user scope — available across all projects):

claude mcp add -s user gerbil \
  -e GERBIL_MCP_GXI_PATH=/opt/gerbil/bin/gxi \
  -- node /absolute/path/to/gerbil-mcp/dist/index.js

Or for a single project only:

claude mcp add -s project gerbil \
  -e GERBIL_MCP_GXI_PATH=/opt/gerbil/bin/gxi \
  -- node /absolute/path/to/gerbil-mcp/dist/index.js

This writes the config to ~/.claude.json (user scope) or .mcp.json in the project root (project scope). Start a new Claude Code session to pick up the server.

Auto-approve all Gerbil tools

By default Claude Code asks for confirmation each time an MCP tool is called. Since the Gerbil tools are read-only introspection (no filesystem writes, no network access), you can safely auto-approve them all with a wildcard in your project's .claude/settings.local.json (local, not checked in) or ~/.claude/settings.json (user scope):

{
  "permissions": {
    "allow": [
      "mcp__gerbil__*"
    ]
  }
}

GitHub Copilot (VS Code)

Add a .vscode/mcp.json file to your project:

{
  "servers": {
    "gerbil": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gerbil-mcp/dist/index.js"],
      "env": {
        "GERBIL_MCP_GXI_PATH": "/opt/gerbil/bin/gxi"
      }
    }
  }
}

Or add it to your VS Code user settings (settings.json) to make it available across all projects:

{
  "mcp": {
    "servers": {
      "gerbil": {
        "type": "stdio",
        "command": "node",
        "args": ["/absolute/path/to/gerbil-mcp/dist/index.js"],
        "env": {
          "GERBIL_MCP_GXI_PATH": "/opt/gerbil/bin/gxi"
        }
      }
    }
  }
}

GitHub Copilot Coding Agent

The Copilot coding agent runs in a GitHub Actions environment. Configure MCP servers in your repository settings on GitHub.com under Settings → Copilot → Coding agent, using this JSON:

{
  "mcpServers": {
    "gerbil": {
      "type": "stdio",
      "command": "node",
      "args": ["/home/runner/gerbil-mcp/dist/index.js"],
      "tools": ["*"],
      "env": {
        "GERBIL_MCP_GXI_PATH": "$COPILOT_MCP_GERBIL_GXI_PATH"
      }
    }
  }
}

Since the agent runs on a GitHub Actions runner, Gerbil and this server must be installed during setup. Create .github/workflows/copilot-setup-steps.yml:

name: "Copilot Setup Steps"
on: workflow_dispatch

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      # Install Gerbil — adjust to your preferred method
      - name: Install Gerbil
        run: |
          # Example: install from a release or package manager
          # See https://cons.io/guide/install.html
          sudo apt-get update && sudo apt-get install -y gerbil

      # Clone and build gerbil-mcp
      - name: Setup gerbil-mcp
        run: |
          git clone https://github.com/ober/gerbil-mcp.git /home/runner/gerbil-mcp
          cd /home/runner/gerbil-mcp
          npm install
          npm run build

Add a COPILOT_MCP_GERBIL_GXI_PATH secret in your repository's copilot environment (e.g. /usr/bin/gxi) pointing to the gxi binary.

GitHub Copilot CLI

Add the server to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "gerbil": {
      "type": "local",
      "command": "node",
      "args": ["/absolute/path/to/gerbil-mcp/dist/index.js"],
      "env": {
        "GERBIL_MCP_GXI_PATH": "/opt/gerbil/bin/gxi"
      },
      "tools": ["*"]
    }
  }
}

To auto-load Gerbil-specific instructio