Go-Zero MCP Tool

You have a fast, MCP-powered tool that helps you scaffold and manage go-zero projects through a Claude Desktop client. It lets you generate services, models, specs, templates, configurations, and more, all via concise MCP commands and automated workflows.

How to use

You use an MCP client to interact with the Go-Zero MCP Tool. Through the client, you can create API services, RPC services, generate code from API specs, build models from databases, create sample API specifications, and generate configurations and templates for your projects. You can also analyze existing projects, validate inputs, and query documentation.

How to install

Prerequisites: you need Go 1.19 or later and the Go toolchain for building and running MCP tools. You also need the Claude Desktop client or another MCP-compatible client.

Step-by-step setup:

1. Create a directory for your MCP tool and enter it.

2. Initialize a Go module.

3. Install dependencies for the MCP tool and its SDK.

4. Save the main tool code as a file named main.go.

5. Build the tool to produce an executable named go-zero-mcp.

Configuration and runtime setup

Configure your Claude Desktop MCP settings to point to the local MCP tool. You add a server entry with a command path to your built MCP tool and the environment variable for the GoCTL path so the tool can locate the goctl utility.

Example configuration for macOS, Linux, and Windows is shown below. Use the appropriate snippet for your platform.

Examples of key configurations

{
  "mcpServers": {
    "mcp_zero": {
      "command": "/path/to/your/mcp-zero",
      "env": {
        "GOCTL_PATH": "/Users/yourname/go/bin/goctl"
      }
    }
  }
}

Available tools and what they do

The toolset includes a collection of commands to scaffold and manage Go-Zero projects. These tools can create API services, RPC services, generate API code from specifications, create models from databases, create sample API specifications, analyze projects, generate configuration files, produce common templates, query documentation, and validate inputs.

Notes on usage patterns

Follow these practical patterns: create an API service on a chosen port, scaffold an RPC service from a protobuf definition, generate API code from an .api specification, turn a database schema into models, and generate a default configuration file for your service. Validate inputs before generating code to catch errors early.

Troubleshooting and tips

If you encounter issues, verify that goctl is installed and available in your PATH, ensure the MCP tool executable has proper permissions, and confirm database connection strings or DDL sources are accessible. For debugging, you can enable debug logging by setting an environment variable in your shell.

Security and best practices

Keep your MCP tool up to date, manage configuration per environment (dev, test, prod), and avoid exposing sensitive endpoints. Use descriptive, consistent service names and ports to reduce conflicts, and validate inputs before generation.

Troubleshooting

Common issues include the goctl command not found, insufficient permissions on the MCP tool, or database connectivity problems. Ensure the goctl binary is installed and reachable, grant execute permissions to the MCP tool, and verify all connection strings and credentials.

Notes on building and running

Build the MCP tool and run the resulting executable. The tool integrates with go-zero's code generation flow to produce production-ready code and configurations.

Available tools

create_api_service

Creates a new go-zero API service with customizable port and code style.

create_rpc_service

Generates a new go-zero RPC service from a protobuf definition.

generate_api_from_spec

Generates go-zero API code from an API specification file.

generate_model

Generates database model code from a database schema or DDL.

create_api_spec

Creates a sample API specification file for a service.

analyze_project

Analyzes an existing go-zero project to understand structure and dependencies.

generate_config

Generates configuration files for go-zero services with proper structure.

generate_template

Creates common code templates such as middleware, error handlers, and deployment templates.

query_docs

Queries go-zero documentation and migration guides.

validate_input

Validates API specs, protobuf definitions, or configuration files.