mcp-server-zig

MCP server that provides Zig language intelligence for Claude Code. Wraps ZLS (Zig Language Server) and exposes 8 tools for diagnostics, formatting, hover info, go-to-definition, references, completions, document symbols, and building.

Prerequisites

• Node.js >= 18
• Zig compiler on PATH (zig version)
• ZLS on PATH (zls --version)

# macOS
brew install zig zls

# Or download from:
# https://ziglang.org/download/
# https://github.com/zigtools/zls/releases

Installation

Add to Claude Code:

claude mcp add --transport stdio mcp-server-zig -- npx -y mcp-server-zig

Or from source:

git clone https://github.com/sadopc/mcp-server-zig.git
cd mcp-server-zig
pnpm install && pnpm build
claude mcp add --transport stdio zig -- node $(pwd)/build/index.js

Tools

zig_diagnostics

Get errors and warnings for a Zig source file.

| Parameter | Type | Description | |-----------|------|-------------| | file_path | string | Absolute path to the .zig file |

zig_format

Format Zig code using zig fmt.

| Parameter | Type | Description | |-----------|------|-------------| | file_path | string? | Path to .zig file to format in-place | | code | string? | Zig source code string to format |

Provide either file_path or code, not both.

zig_hover

Get type information and documentation for a symbol at a position.

| Parameter | Type | Description | |-----------|------|-------------| | file_path | string | Absolute path to the .zig file | | line | number | Zero-based line number | | character | number | Zero-based character offset |

zig_definition

Go to definition — find where a symbol is defined.

| Parameter | Type | Description | |-----------|------|-------------| | file_path | string | Absolute path to the .zig file | | line | number | Zero-based line number | | character | number | Zero-based character offset |

zig_references

Find all references to a symbol.

| Parameter | Type | Description | |-----------|------|-------------| | file_path | string | Absolute path to the .zig file | | line | number | Zero-based line number | | character | number | Zero-based character offset |

zig_completions

Get completion suggestions at a position.

| Parameter | Type | Description | |-----------|------|-------------| | file_path | string | Absolute path to the .zig file | | line | number | Zero-based line number | | character | number | Zero-based character offset | | limit | number? | Max completions to return (default: 20) |

zig_document_symbols

Get the document symbol outline (functions, structs, variables, etc.).

| Parameter | Type | Description | |-----------|------|-------------| | file_path | string | Absolute path to the .zig file |

zig_build

Run zig build in a project directory.

| Parameter | Type | Description | |-----------|------|-------------| | project_path | string | Path to project directory (containing build.zig) | | args | string[]? | Additional args for zig build |

How It Works

Claude Code ←(MCP/stdio)→ mcp-server-zig ←(LSP/stdio)→ ZLS subprocess
                                          ←(shell exec)→ zig fmt / zig build

• ZLS tools (diagnostics, hover, definition, references, completions, symbols): The server spawns ZLS as a subprocess, communicates via LSP over stdio. ZLS is started lazily on first tool call and auto-restarts on crash.
• CLI tools (format, build): These call zig fmt and zig build directly — no ZLS needed.

Troubleshooting

"ZLS spawn error" — ZLS is not installed or not on PATH. Run which zls to verify.

"zig fmt failed" — Zig compiler is not installed or not on PATH. Run which zig to verify.

Diagnostics are empty — ZLS needs time to analyze the file. The server waits 200ms by default. For large projects, diagnostics may take longer to appear.

Tools hang — Check that ZLS is compatible with your Zig version. ZLS and Zig versions should match.

License

MIT