You can run the zig-mcp MCP server to connect AI coding assistants to ZLS using the Language Server Protocol. It lets you access Zig language intelligence through a stable MCP interface, coordinating code intelligence with your Zig project workspace.

How to use

Set up zig-mcp as your MCP server, then connect your preferred MCP client (such as Claude Code, Cursor, Windsurf, or any MCP-compatible client). You’ll enjoy on-demand code intelligence for Zig: hover details, go-to-definition, references, completions, diagnostics, formatting, renaming, and workspace-wide symbol and action support. zig-mcp runs ZLS as a child process and talks to your AI assistant via MCP, while ZLS communicates back through the LSP channel.

How to install

Prerequisites you must have before installing zig-mcp:

• • Zig 0.15.2+

Recommended installation via Claude Code (plugin-driven)

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

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

Or run this as a single command from your terminal:

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

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

Manual build (from source)

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

The resulting binary is located at `zig-out/bin/zig-mcp`.

Setup (manual install only)

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

Configure the MCP server for Claude Code and other clients. You must provide the absolute path to the zig-mcp binary and the Zig project workspace you want to associate with this server.

Claude Code configuration (global)

{
  "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 project configuration

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

Place this in your project’s `.cursor/mcp.json`.

Windsurf configuration

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

Place this in your Windsurf config at ~/.codeium/windsurf/mcp_config.json.

## Options

Available command-line options for zig-mcp include the workspace, ZLS path, and help/version controls.

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

## Tools

zig-mcp exposes a suite of code intelligence actions that you can invoke through the MCP interface. These tools are backed by ZLS and tailored for Zig language support.

## Build & run

When you want to build or test Zig projects while using the MCP server, you can access build-related tools through the provided commands.

zig_build Run zig build with optional args zig_test Run tests (whole project or single file, with optional filter) zig_check Run zig ast-check on a file zig_version Show Zig and ZLS versions zig_manage Manage Zig versions via zvm

## How it works

zig-mcp starts ZLS as a child process and communicates with it over stdin/stdout using the LSP protocol. It then speaks MCP to the AI assistant, translating between MCP requests and LSP messages. Three threads coordinate activity: main handles MCP requests, reader tracks LSP responses by request ID, and stderr forwards ZLS error output to the log. If ZLS crashes, zig-mcp restarts it and reopens all documents. Documents are opened lazily in ZLS as you access them.

## Development

If you are developing or testing locally, you can build and run tests with these commands.

build

zig build

run tests (about 75 unit tests)

zig build test

run a manual interaction

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

## License

MIT

## Available tools

### zig\_hover

Type info and docs for a symbol

### zig\_definition

Go to definition

### zig\_references

Find all references

### zig\_completion

Completion suggestions

### zig\_diagnostics

Errors and warnings for a file

### zig\_format

Format a file

### zig\_rename

Rename a symbol across the workspace

### zig\_document\_symbols

List all symbols in a file

### zig\_workspace\_symbols

Search symbols across the project

### zig\_code\_action

Quick fixes and refactors for a range

### zig\_signature\_help

Function signature at cursor

### zig\_build

Run zig build with optional args

### zig\_test

Run tests (whole project or single file, with optional filter)

### zig\_check

Run zig ast-check on a file

### zig\_version

Show Zig and ZLS versions

### zig\_manage

Manage Zig versions via zvm