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
-
Go (1.19 or later)
-
go-zero CLI (goctl): Install with
go install github.com/zeromicro/go-zero/tools/goctl@latest -
Claude Desktop (or other MCP-compatible client)
For detailed installation instructions, see the Quick Start Guide.
Installation
-
Create a new directory for your MCP tool:
bash mkdir go-zero-mcp && cd go-zero-mcp -
Initialize Go module:
bash go mod init go-zero-mcp -
Install dependencies:
bash go get github.com/modelcontextprotocol/go-sdk go get gopkg.in/yaml.v3 -
Save the main tool code as
main.go -
Build the tool:
bash 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:```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`:```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:```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```text
Please create a new go-zero API service called "user-service" on port 8080
Creating an RPC Service```text
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```text
Generate go-zero models from my MySQL database with connection string "user:password@tcp(localhost:3306)/mydb"
Creating an API Specification```text
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```text
Analyze my go-zero project in /path/to/myproject to understand its structure
Generating Configuration```text
Generate a production configuration file for my "order-service" API service
### Generating Templates```text
Generate a middleware template for my "auth-service"
Querying Documentation```text
How do I implement JWT authentication in go-zero?
``````text
How do I migrate from Express.js to go-zero?
### Validating Input```text
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:```text
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:```bash
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
