Go-Zero MCP Tool

A Model Context Protocol (MCP) tool that helps developers quickly scaffold and generate go-zero projects with ease.

Quick Start

New to mcp-zero? Check out our Quick Start Guide for a step-by-step tutorial on getting started!

The quickstart covers:

• Installation and configuration
• Creating your first API service
• Common use cases and workflows
• Integration with Claude Desktop

Features

Core Service Generation

• Create API Services: Generate new REST API services with customizable ports and styles
• Create RPC Services: Generate gRPC services from protobuf definitions
• Generate API Code: Convert API specification files to Go code
• Generate Models: Create database models from various sources (MySQL, PostgreSQL, MongoDB, DDL)
• Create API Specs: Generate sample API specification files

Advanced Features

• Analyze Projects: Analyze existing go-zero projects to understand structure and dependencies
• Manage Configuration: Generate configuration files with proper structure validation
• Generate Templates: Create middleware, error handlers, and deployment templates
• Query Documentation: Access go-zero concepts and migration guides from other frameworks
• Validate Input: Comprehensive validation for API specs, protobuf definitions, and configurations

Prerequisites

1. Go (1.19 or later)

2. go-zero CLI (goctl): Install with go install github.com/zeromicro/go-zero/tools/goctl@latest

3. Claude Desktop (or other MCP-compatible client)

For detailed installation instructions, see the Quick Start Guide.

Installation

1. Create a new directory for your MCP tool:

   mkdir go-zero-mcp && cd go-zero-mcp

2. Initialize Go module:

   go mod init go-zero-mcp

3. Install dependencies:

   go get github.com/modelcontextprotocol/go-sdk
   go get gopkg.in/yaml.v3

4. Save the main tool code as main.go

5. Build the tool:

   go build -o go-zero-mcp main.go

Configuration for Claude Desktop

Add this configuration to your Claude Desktop MCP settings:

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Linux

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-zero": {
      "command": "/path/to/your/mcp-zero",
      "env": {
        "GOCTL_PATH": "/usr/local/bin/goctl"
      }
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-zero": {
      "command": "C:\\path\\to\\your\\mcp-zero.exe",
      "env": {
        "GOCTL_PATH": "C:\\Go\\bin\\goctl.exe"
      }
    }
  }
}

Available Tools

1. create_api_service

Creates a new go-zero API service.

Parameters:

• service_name (required): Name of the API service
• port (optional): Port number (default: 8888)
• style (optional): Code style - "go_zero" or "gozero" (default: "go_zero")
• output_dir (optional): Output directory (default: current directory)

2. create_rpc_service

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

Parameters:

• service_name (required): Name of the RPC service
• proto_content (required): Protobuf definition content
• output_dir (optional): Output directory (default: current directory)

3. generate_api_from_spec

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

Parameters:

• api_file (required): Path to the .api specification file
• output_dir (optional): Output directory (default: current directory)
• style (optional): Code style - "go_zero" or "gozero" (default: "go_zero")

4. generate_model

Generates database model code from database schema.

Parameters:

• source_type (required): Source type - "mysql", "postgresql", "mongo", or "ddl"
• source (required): Database connection string or DDL file path
• table (optional): Specific table name (for database sources)
• output_dir (optional): Output directory (default: "./model")

5. create_api_spec

Creates a sample API specification file.

Parameters:

• service_name (required): Name of the API service
• endpoints (required): Array of endpoint objects with method, path, and handler
• output_file (optional): Output file path (default: service_name.api)

6. analyze_project

Analyzes an existing go-zero project structure and dependencies.

Parameters:

• project_dir (required): Path to the project directory
• analysis_type (optional): Type of analysis - "api", "rpc", "model", or "full" (default: "full")

7. generate_config

Generates configuration files for go-zero services.

Parameters:

• service_name (required): Name of the service
• service_type (required): Service type - "api" or "rpc"
• config_type (optional): Configuration type - "dev", "test", or "prod" (default: "dev")
• output_file (optional): Output file path (default: etc/{service_name}.yaml)

8. generate_template

Generates common code templates for go-zero services.

Parameters:

• template_type (required): Template type - "middleware", "error_handler", "dockerfile", "docker_compose", or "kubernetes"
• service_name (required): Name of the service
• output_path (optional): Output file path (uses defaults based on template type)

9. query_docs

Queries go-zero documentation and migration guides.

Parameters:

• query (required): Natural language query about go-zero concepts or migration
• doc_type (optional): Documentation type - "concept", "migration", or "both" (default: "both")

10. validate_input

Validates API specs, protobuf definitions, or configuration files.

Parameters:

• input_type (required): Input type - "api_spec", "proto", or "config"
• content (required): Content to validate
• strict (optional): Enable strict validation mode (default: false)

Usage Examples

Creating a New API Service

Please create a new go-zero API service called "user-service" on port 8080

Creating an RPC Service

Create a new go-zero RPC service called "auth-service" with this protobuf definition:

syntax = "proto3";

package auth;

option go_package = "./auth";

service AuthService {
  rpc Login(LoginRequest) returns (LoginResponse);
  rpc Logout(LogoutRequest) returns (LogoutResponse);
}

message LoginRequest {
  string username = 1;
  string password = 2;
}

message LoginResponse {
  string token = 1;
  int64 expires_at = 2;
}

message LogoutRequest {
  string token = 1;
}

message LogoutResponse {
  bool success = 1;
}

Generating Models from Database

Generate go-zero models from my MySQL database with connection string "user:password@tcp(localhost:3306)/mydb"

Creating an API Specification

Create an API specification for a "blog-service" with these endpoints:
- GET /api/posts (handler: GetPostsHandler)
- POST /api/posts (handler: CreatePostHandler)
- GET /api/posts/:id (handler: GetPostHandler)
- PUT /api/posts/:id (handler: UpdatePostHandler)
- DELETE /api/posts/:id (handler: DeletePostHandler)

Analyzing a Project

Analyze my go-zero project in /path/to/myproject to understand its structure

Generating Configuration

Generate a production configuration file for my "order-service" API service

Generating Templates

Generate a middleware template for my "auth-service"

Querying Documentation

How do I implement JWT authentication in go-zero?

How do I migrate from Express.js to go-zero?

Validating Input

Validate this API spec file at /path/to/service.api with strict mode enabled

Project Structure

After building, your MCP server will have the following structure:

mcp-zero/
├── main.go                    # Entry point and tool registration
├── tools/                     # Tool implementations
│   ├── create_api_service.go
│   ├── create_rpc_service.go
│   ├── generate_api.go
│   ├── generate_model.go
│   ├── create_api_spec.go
│   ├── analyze_project.go
│   ├── generate_config.go
│   ├── generate_template.go
│   ├── query_docs.go
│   └── validate_input.go
├── internal/                  # Internal packages
│   ├── analyzer/             # Project analysis
│   ├── validation/           # Input validation
│   ├── security/             # Credential handling
│   ├── templates/            # Code templates
│   ├── docs/                 # Documentation database
│   ├── logging/              # Structured logging
│   └── metrics/              # Performance metrics
└── tests/                     # Test suites
    ├── integration/
    └── unit/

Architecture

The MCP server is built with:

• MCP SDK: Uses github.com/modelcontextprotocol/go-sdk for protocol implementation
• Transport: stdio-based communication with Claude Desktop
• Code Generation: Leverages go-zero's goctl CLI tool for generating production-ready code
• Validation: Comprehensive input validation for safety and correctness
• Security: Safe credential handling with environment variable substitution
• Observability: Built-in logging and metrics for monitoring tool performance

Best Practices

1. Service Naming: Use lowercase with hyphens (e.g., "user-service", "auth-api")
2. Port Configuration: Choose unique ports for each service (8080-8090 range recommended)
3. Code Style: Stick to "go_zero" style for consistency with official conventions
4. Configuration: Use environment-specific configs (dev, test, prod)
5. Documentation: Query docs regularly to stay aligned with go-zero best practices
6. Validation: Always validate inputs before generation to catch errors early

Troubleshooting

Common Issues

1. goctl command not found: Make sure goctl is installed and in your PATH
2. Permission denied: Ensure the MCP tool executable has proper permissions
3. Database connection errors: Verify connection strings and database accessibility

Debug Mode

To enable debug logging, set the environment variable:

export MCP_DEBUG=1

Contributing

Feel free to extend this tool with additional go-zero features such as:

• Dockerfile generation
• Kubernetes manifest generation
• Docker Compose file creation
• API documentation generation
• Testing template creation

License

MIT License - see LICENSE file for details.

Copyright (c) 2025 go-zero team