zig-mcp

MCP server for Zig that connects AI coding assistants to ZLS via the Language Server Protocol.

Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

AI assistant    zig-mcp    ZLS
                                    |
                             zig build / test / check

Requirements

• Zig 0.17.0-dev.1415+64dfaa568 or newer
• ZLS (auto-detected from PATH, or specify with `--zls-path`)

Install

Claude Code plugin (recommended)

Install directly from the Claude Code interface — no manual build needed:

# 1. Add the marketplace
/plugin marketplace add nzrsky/zig-mcp

# 2. Install the plugin
/plugin install zig-mcp@zig

Or as a one-liner from the terminal:

claude plugin marketplace add nzrsky/zig-mcp && claude plugin install zig-mcp@zig

The binary is built automatically on first use. Just make sure `zig` and `zls` are in your PATH.

Manual build

git clone https://github.com/nzrsky/zig-mcp.git
cd zig-mcp
zig build -Doptimize=ReleaseFast

Binary is at `zig-out/bin/zig-mcp`.

Setup (manual install only)

If you installed via the plugin system, skip this section — everything is configured automatically.

Claude Code

# add globally
claude mcp add zig-mcp -- /absolute/path/to/zig-mcp --workspace /path/to/your/zig/project

# add for current project only
claude mcp add --scope project zig-mcp -- /absolute/path/to/zig-mcp --workspace /path/to/your/zig/project

Or edit `~/.claude/mcp_servers.json`:

{
  "mcpServers": {
    "zig-mcp": {
      "command": "/absolute/path/to/zig-mcp",
      "args": ["--workspace", "/path/to/your/zig/project"]
    }
  }
}

> If you omit `--workspace`, zig-mcp uses the current working directory.

Cursor

Add to `.cursor/mcp.json` in your project:

{
  "mcpServers": {
    "zig-mcp": {
      "command": "/absolute/path/to/zig-mcp",
      "args": ["--workspace", "/path/to/your/zig/project"]
    }
  }
}

Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

{
  "mcpServers": {
    "zig-mcp": {
      "command": "/absolute/path/to/zig-mcp",
      "args": ["--workspace", "/path/to/your/zig/project"]
    }
  }
}

Options

--workspace, -w    Project root directory (default: cwd)
--zls-path         Path to ZLS binary (default: auto-detect from PATH)
--help, -h               Show help
--version                Show version

Tools

All of these answer from ZLS's semantic model — the part a shell and a text

search cannot reach.

What is deliberately absent

There is no `zig_build`, `zig_test`, `zig_format`, `zig_version`, `zig_check`

or `zig_manage`. They used to exist and wrapped `zig build`, `zig test`,

`zig fmt`, `zig version`, `zig ast-check` and `zvm` — and a wrapper loses to

the shell it wraps: no pipes, no redirection, no working

directory of its own. Session transcripts settle it: 526 `zig build`

invocations through the shell, zero calls to the tool. Run those with your

shell.

How it works

zig-mcp spawns ZLS as a child process and talks to it over stdin/stdout using the LSP protocol (Content-Length framing). On the other side, it speaks MCP (newline-delimited JSON-RPC) to the AI assistant.

Three threads:

• main -- reads MCP requests, dispatches tool calls, writes responses
• reader -- reads LSP responses from ZLS, correlates by request ID
• stderr -- forwards ZLS stderr to the server log

If ZLS crashes, zig-mcp automatically restarts it and re-opens all tracked documents.

Files are opened in ZLS lazily on first access, and re-synced (`didChange`) whenever their contents change on disk -- no need to manage document state manually.

Development

# build
zig build

# run tests (162 unit tests, including a fake-ZLS harness)
zig build test

# quality gates: lint, coverage, dead code, mutants
make lint cov deadcode mutants

# run manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | \
  zig-out/bin/zig-mcp --workspace . 2>/dev/null

License

MIT