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