Go MCP Server Starter
Production-ready starter template for building a Model Context Protocol (MCP) server in Go.
Features
- Official Go MCP SDK bootstrap with stdio transport
- Clean architecture with separate registries for tools, resources, and prompts
- Service-layer design (thin MCP handlers, testable business logic)
- Centralized error handling and reusable validation helpers
- Structured JSON logging with
log/slog .envsupport with typed config parsing + validation- Graceful shutdown on
SIGINT/SIGTERMwith configurable timeout - Multi-stage Docker build with small distroless runtime image
Project Layout
cmd/server: application entrypoint and lifecycle managementconfig:.envloading, environment parsing, and config validationinternal/app: MCP server bootstrap and registration wiringinternal/service: business logic servicesinternal/errors: centralized app error model + MCP tool guardsinternal/validation: reusable input validation helperstools: MCP tools and centralized tool registryresources: MCP resources and centralized resource registryprompts: MCP prompts and centralized prompt registrylogging: structured logger wrappertests: service and tool tests
Configuration
Supported environment variables:
- MCP_SERVER_NAME (default: go-mcp-server)
- MCP_SERVER_VERSION (default: 0.1.0)
- MCP_ENV (default: development) allowed: development · staging · production · test
- MCP_LOG_LEVEL (default: info) allowed: debug · info · warn · error
- MCP_PORT (default: 8080)
- MCP_SHUTDOWN_TIMEOUT (default: 10s)
- MCP_ENV_FILE (default: .env)
Use .env.example as your template.
Run Locally
- Copy env template:```bash
cp .env.example .env
2. Start server:```bash
go run ./cmd/server
Run Tests```bash
go test ./...
## Sample MCP Tools
Included starter tools:
- `greet`: greet a user by name
- `health_check`: server status, UTC timestamp, server name/version
- `calculator`: arithmetic with validation and errors
- `echo`: returns normalized text + length
- `server_time`: current UTC time + unix timestamp
## Docker
Build image:```bash
docker build -t go-mcp-server:latest .
Run container (stdio MCP, keep stdin open):```bash
docker run --rm -i --env-file .env go-mcp-server:latest
Example with inline env vars:```bash
docker run --rm -i \
-e MCP_SERVER_NAME=go-mcp-server \
-e MCP_SERVER_VERSION=0.1.0 \
-e MCP_ENV=production \
-e MCP_LOG_LEVEL=info \
-e MCP_PORT=8080 \
-e MCP_SHUTDOWN_TIMEOUT=10s \
go-mcp-server:latest
Credits
Created for this project by glen0xFFF.
