Local MCP Development with Zig and Gemini CLI

Leveraging Gemini CLI and the underlying Gemini LLM to build Model Context Protocol (MCP) AI...

title: Local MCP Development with Zig and Gemini CLI published: true series: MCP-Palooza date: 2026-01-31 16:10:28 UTC tags: mcps,aiagent,carmen,geminicli canonical_url: https://xbill999.medium.com/local-mcp-development-with-zig-and-gemini-cli-439d60a80fe6

Leveraging Gemini CLI and the underlying Gemini LLM to build Model Context Protocol (MCP) AI applications in the Zig programming language with a local development environment.

Why not just use Python?

Python has traditionally been the main coding language for ML and AI tools. One of the strengths of the MCP protocol is that the actual implementation details are independent of the development language. The reality is that not every project is coded in Python- and MCP allows you to use the latest AI approaches with other coding languages.

Zig? Are you just inventing languages now?

The goal of this article is to provide a minimal viable basic working MCP stdio server in Zig that can be run locally without any unneeded extra code or extensions.

The ZigMCP library is here:

GitHub - muhammad-fiaz/mcp.zig: A comprehensive Model Context Protocol (MCP) library for Zig - bringing MCP support to the Zig ecosystem.

What Is Zig?

Zig is a modern, open-source, general-purpose systems programming language and toolchain designed for robustness, optimality, and clarity. Created by Andrew Kelley, it aims to be a “better C,” offering manual memory management, no hidden allocations, and powerful compile-time code execution (comptime). Zig also functions as a C/C++ compiler and build system.

The main site for Zig is here:

Home ⚡ Zig Programming Language

Installing Zig

The step by step instructions vary by platform. Here is a site with starter steps for a Debian based system:

How to Install Zig on Debian: The Easy Way with debian.griffo.io

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

gemini

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Zig MCP Documentation

This Zig MCP page provides samples and documentation for getting started:

mcp.zig | Model Context Protocol for Zig

Where do I start?

The strategy for starting MCP development is a incremental step by step approach.

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, a minimal Hello World Style Zig MCP Server is built with stdio transport. This server is validated with Gemini CLI in the local environment.

This setup validates the connection from Gemini CLI to the local process via MCP. The MCP client (Gemini CLI) and the MCP server both run in the same local environment.

Next- the basic MCP server is extended with Gemini CLI to add several new MCP tools in standard code.

Setup the Basic Environment

At this point you should have a working Zig build environment and a working Gemini CLI installation. The next step is to clone the GitHub samples repository with support scripts:

cd ~
git clone https://github.com/xbill9/gemini-cli-codeassist

Then run init.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:

cd gemini-cli-codeassist
source init.sh

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

cd gemini-cli-codeassist
source set_env.sh

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

Hello World with STDIO Transport

One of the key features that the standard MCP libraries provide is abstracting various transport methods.

The high level MCP tool implementation is the same no matter what low level transport channel/method that the MCP Client uses to connect to a MCP Server.

The simplest transport that the SDK supports is the stdio (stdio/stdout) transport — which connects a locally running process. Both the MCP client and MCP Server must be running in the same environment.

The connection over stdio will look similar to this:

    // Run the server using stdio transport
    try server.run(.{ .stdio = {} });

Zig Package Information

The code depends on several standard Ziglibraries for MCP and logging:

const std = @import("std");
const mcp = @import("mcp");

Installing and Running the Zig Code

Run the install make release target on the local system:

xbill@penguin:~/gemini-cli-codeassist/mcp-stdio-zig$ make
zig build
Linked zig-out/bin/mcp-stdio-zig to server

To lint the code:

xbill@penguin:~/gemini-cli-codeassist/mcp-stdio-zig$ make lint
zig fmt --check .
zig build -Doptimize=ReleaseFast

To test the code:

xbill@penguin:~/gemini-cli-codeassist/mcp-stdio-zig$ make test
zig build
Linked zig-out/bin/mcp-stdio-zig to server
zig build test
python3 test_server.py
Testing 'greet' tool...
✓ initialize successful
✓ notifications/initialized sent
✓ tools/list successful
✓ tools/call (greet) successful

All tests passed!

Gemini CLI settings.json

In this example — the C source code uses a compiled binary that can be called directly from Gemini CLI.

The default Gemini CLI settings.json has an entry for the source:

 {
    "mcpServers": {
      "mcp-stdio-zig": {
        "command": "$HOME/gemini-cli-codeassist/mcp-stdio-zig/server"
        }
      }
    }

Validation with Gemini CLI

Finally- Gemini CLI is restarted and the MCP connection over stdio to the C Code is validated, The full Gemini CLI Session will start:

> /mcp schema

Configured MCP servers:

🟢 mcp-stdio-zig - Ready (1 tool)
  Tools:
  - greet
    Get a greeting from a local stdio server.
      Parameters:
      {
        "type": "object"
      }

Configured MCP servers:

🟢 mcp-stdio-zig - Ready (1 tool)
  Tools:
  - greet

> greet Carmen!

✦ I will read the src/main.zig file to understand how the greet tool is implemented and what parameters it expects.
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ ReadFile src/main.zig │
│ │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ I will call the greet tool with the parameter param set to "Carmen!".
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ greet (mcp-stdio-zig MCP Server) {"param":"Carmen!"} │
│ │
│ Carmen! │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ OK. I've greeted Carmen! (The tool returned "Carmen!").

Extending the MCP Server with Gemini CLI

Now that the basic MCP functionality has been tested and verified with Gemini CLI- the Zig MCP server code can be extended with new MCP tools:

> with the Zig project add new MCP tools - 
one that gets Zig system information, 
one that gets server information
and one that gets the current time

Gemini CLI will get right to work:

│ 140 + fn serverInfoHandler(allocator: std.mem.Allocator, _: ?std.json.Value) mcp.tools.ToolError!mcp.tools.ToolResult { │
│ 141 + logInfo("Executed server-info tool"); │
│ 142 + │
│ 143 + const info = "Server: mcp-stdio-zig, Version: 0.1.0"; │
│ 144 + var items = allocator.alloc(mcp.types.ContentItem, 1) catch return mcp.tools.ToolError.OutOfMemory; │
│ 145 + items[0] = .{ .text = .{ .text = try allocator.dupe(u8, info) } }; │
│ 146 + │
│ 147 + return mcp.tools.ToolResult{ │
│ 148 + .content = items, │
│ 149 + .is_error = false, │
│ 150 + }; │
│ 151 + } │
│ 152 + │ │

Once completed — the changes will be summarized:

✦ I have successfully added the requested tools (zig-info, server-info, current-time) and verified them. I also committed the changes.

Restart Gemini CLI and check for the new MCP tools:

xbill@penguin:~/gemini-cli-codeassist/mcp-stdio-zig$ make
zig build
Linked zig-out/bin/mcp-stdio-zig to server

And list the new MCP Tools:

> /mcp list

Configured MCP servers:

🟢 mcp-stdio-zig - Ready (4 tools)
  Tools:
  - current-time
  - greet
  - server-info
  - zig-info

to run the tools:

> current-time

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ current-time (mcp-stdio-zig MCP Server) {} │
│ │
│ Timestamp: 1769875173 │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

and Zig information:

> zig-info

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ zig-info (mcp-stdio-zig MCP Server) {} │
│ │
│ Zig Version: 0.15.2, OS: linux, Arch: x86_64 │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ I've confirmed you're running Zig 0.15.2 on Linux x86_64. How can I assist you with your project today?                                                                                                               

and system information:

> server-info

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ server-info (mcp-stdio-zig MCP Server) {} │
│ │
│ Server: mcp-stdio-zig, Version: 0.1.0 │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ I've confirmed that the server is mcp-stdio-zig version 0.1.0. What would you like to do next?

This information can be used in the context:

> based on the MCP tools summarize the Zig environment

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ ReadFile src/main.zig │
│ │
│ │
│ ✓ ReadFile build.zig │
│ │
│ │
│ ✓ ReadFile build.zig.zon │
│ │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ Based on the tools and codebase, here is a summary of the Zig environment:

   - Zig Version: 0.15.2
   - Operating System: Linux (x86_64)
   - MCP Server Name: mcp-stdio-zig (v0.1.0)
   - Primary Dependency: mcp.zig (v0.0.1), a Model Context Protocol implementation for Zig.
   - Communication: Standard Input/Output (stdio) for MCP protocol, with structured JSON logging to stderr.
   - Exposed Tools:
       - greet: Returns a greeting message (parameterized).
       - zig-info: Reports Zig version, OS, and Architecture.
       - server-info: Returns server name and version.
       - current-time: Provides the current system timestamp.

And finally - the all-important question:

> would Ferris the Rust Crab beat Carmen in a smack-down?

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ GoogleSearch Searching the web for: "who is carmen programming language mascot" │
│ │
│ Search results for "who is carmen programming language mascot" returned. │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ In a hypothetical smack-down between Ferris the Rust Crab and Carmen the Zig Allocgator, it would be a battle of Safety vs. Control.

  Here is the "Tale of the Tape":

  🦀 Ferris (The Rustacean)
   * Signature Move: The "Borrow Checker" (Hold). If he grabs you, you cannot move until he says it's safe.
   * Defense: High. His hard shell (Type System) is nearly impenetrable to memory corruption attacks.
   * Weakness: Compile times. He takes a long time to get ready for the fight.

  🐊 Carmen (The Allocgator)
   * Signature Move: "Defer Deinit" (Death Roll). She grabs resources and ensures they are cleaned up eventually, but you have to tell her when.
   * Offense: High. She is extremely fast (Release Mode) and gives you manual control over every bite (byte).
   * Weakness: Use-after-free. If she gets confused, she might bite something that isn't there anymore.

  The Verdict
  It depends on the arena:

   * In a Safe Arena (User Space): Ferris wins by attrition. He just locks down every limb Carmen has until she can't compile a counter-attack.
   * In the Wild (Embedded/Kernel): Carmen has the edge. She can maneuver through tight memory constraints without dragging along a heavy runtime or
     complex abstractions.

  Official Prediction: They wouldn't fight. Ferris would likely try to rewrite Carmen in Rust, and Carmen would just comptime optimize Ferris out of
  existence. They'd end up sharing a drink over their mutual dislike of C++.

Summary

The strategy for using Zig with MCP development with Gemini CLI was validated with an incremental step by step approach.

A minimal stdio transport MCP Server was started from Zig source code and validated with Gemini CLI running as a MCP client in the same local environment.

Gemini CLI was then used to extend the sample Zig code with several MCP tools and use these tools inside the context for the underlying LLM.