zhangpanda/gomcp

**The fast, idiomatic way to build MCP servers in Go.**
中文文档
---
🚀 Quick Links
- **GitHub**: https://github.com/zhangpanda/gomcp
- **Gitee**: https://gitee.com/rilegouasas/gomcp
- **MCP Protocol**: https://modelcontextprotocol.io
---
🎯 What is GoMCP?
GoMCP is a **framework** for building Model Context Protocol (MCP) servers — not just an SDK. Think of it as **"Gin for MCP"**.
MCP is the open protocol that lets AI applications (Claude Desktop, Cursor, Kiro, VS Code Copilot) call external tools, read data sources, and use prompt templates. GoMCP makes building those servers trivial.
Why GoMCP?
| | mcp-go (mark3labs) | Official Go SDK | **GoMCP** |
|---|---|---|---|
| Level | SDK | SDK | **Framework** |
| Schema generation | Manual | jsonschema tag | **mcp tag + auto validation** |
| Middleware | Basic hooks | None | **Full chain (Logger, Auth, RateLimit, OTel…)** |
| Tool groups | No | No | **Yes (user.get, admin.delete)** |
| Import Gin routes | No | No | **✅ One line** |
| Import OpenAPI/Swagger | No | No | **✅ One line** |
| Import gRPC services | No | No | **✅** |
| Built-in auth | No | No | **Bearer / API Key / Basic + RBAC** (Bearer = your token/JWT validator) |
| Inspector UI | No | No | **✅** |
| Test utilities | Basic | No | **mcptest package** |
---
🛠️ Tech Stack
Environment Requirements
| Requirement | Version |
|-------------|---------|
| **Go** | ≥ 1.25 |
| **MCP Protocol** | 2024-11-05 (backward compatible with 2025-11-25) |
> **Note on the Go 1.25 requirement.** GoMCP's go.mod declares go 1.25.0 so the project always builds with the toolchain that ships current security and runtime fixes. If you are running Go 1.21+ locally with the default GOTOOLCHAIN=auto, Go will automatically download and use the matching toolchain for you — no manual upgrade is needed. If you have pinned GOTOOLCHAIN=local, install Go 1.25+ or unset the pin.
Core Dependencies
| Technology | Description |
|------------|-------------|
| **Go standard library** | Framework routing, JSON-RPC, transports — no forced DB/ORM deps |
| **Gin** | Adapter only — import existing Gin routes |
| **gRPC** | Adapter only — import gRPC services |
| **OpenTelemetry** | Optional — distributed tracing |
| **YAML v3** | Provider only — hot-reload tool definitions |
---
🌟 Core Features
🔧 Tool Development
- **Struct-tag auto schema** — define parameters with Go structs and mcp tags, JSON Schema generated automatically
- **Typed handlers** — func(*Context, Input) (Output, error) — no manual parameter parsing
- **Parameter validation** — required, min/max, enum, pattern — checked before your handler runs
- **Component versioning** — register multiple versions, clients call name@version
- **Async tasks** — long-running tools return task ID, with polling and cancellation
🔌 Adapters (Core Differentiator)
- **Gin adapter** — import existing Gin routes as MCP tools with one line
- **OpenAPI adapter** — generate tools from Swagger/OpenAPI 3.x docs
- **gRPC adapter** — import gRPC service methods as MCP tools
🔐 Security
- **BearerAuth** — Bearer token check via your validator (JWT parsing is up to you; this library does not decode JWTs)
- **APIKeyAuth** — API key validation via header
- **BasicAuth** — HTTP Basic authentication
- **RequireRole / RequirePermission** — RBAC authorization on tool groups
🧩 Framework Features
- **Middleware chain** — Logger, Recovery, RequestID, Timeout, RateLimit, OpenTelemetry
- **Tool groups** — organize tools with prefixes and group-level middleware
- **Resource & Prompt** — full MCP support including URI templates and parameterized prompts
- **Auto-completions** — suggest values for prompt/resource arguments
🚀 Production Ready
- **Multiple transports** — stdio (Claude Desktop, Cursor, Kiro) and Streamable HTTP with SSE
- **MCP Inspector** — built-in web debug UI for browsing and testing tools