mcp-go-starter

View on GitHub

A starter repo for building a go MCP server

6 stars GoDeveloper Kits Updated Jun 30, 2025

Documentation

MCP Go Starter

A feature-complete Model Context Protocol (MCP) server template in Go using the official go-sdk. This starter demonstrates all major MCP features with clean, idiomatic Go code.

📚 Documentation

✨ Features

Category	Feature	Description
Tools	`hello`	Basic tool with annotations
`get_weather`	Tool returning structured data
`ask_llm`	Tool that invokes LLM sampling
`long_task`	Tool with 5-second progress updates
`load_bonus_tool`	Dynamically loads a new tool
Resources	`info://about`	Static informational resource
`file://example.md`	File-based markdown resource
Templates	`greeting://{name}`	Personalized greeting
`data://items/{id}`	Data lookup by ID
Prompts	`greet`	Greeting in various styles
`code_review`	Code review with focus areas

🚀 Quick Start

Prerequisites

Go 1.22+
(Optional) air for live reload
(Optional) golangci-lint for linting

Installation

bash

# Clone the repository
git clone https://github.com/SamMorrowDrums/mcp-go-starter.git
cd mcp-go-starter

# Download dependencies
go mod download

Running the Server

stdio transport (for local development):

bash

go run ./cmd/stdio
# Or: make run-stdio

HTTP transport (for remote/web deployment):

bash

go run ./cmd/http
# Or: make run-http
# Server runs on http://localhost:3000

Building Binaries

bash

make build
# Creates bin/stdio and bin/http

🔧 VS Code Integration

This project includes VS Code configuration for seamless development:

1. Open the project in VS Code

2. The MCP configuration is in `.vscode/mcp.json`

3. Build with `Ctrl+Shift+B` (or `Cmd+Shift+B` on Mac)

4. Test the server using VS Code's MCP tools

Using DevContainers

1. Install the Dev Containers extension

2. Open command palette: "Dev Containers: Reopen in Container"

3. Everything is pre-configured and ready to use!

📁 Project Structure

code

.
├── cmd/
│   ├── stdio/
│   │   └── main.go        # stdio transport entrypoint
│   └── http/
│       └── main.go        # HTTP transport entrypoint
├── internal/
│   └── server/
│       ├── server.go      # Server orchestration
│       ├── tools.go       # Tool definitions (hello, get_weather, etc.)
│       ├── resources.go   # Resource and template definitions
│       └── prompts.go     # Prompt definitions
├── .vscode/
│   ├── mcp.json           # MCP server configuration
│   ├── tasks.json         # Build/run tasks
│   └── extensions.json
├── .devcontainer/
│   └── devcontainer.json
├── .air.toml              # Live reload configuration
├── .golangci.yml          # Linter configuration
├── go.mod
├── Makefile
└── README.md

🛠️ Development

bash

# Development with live reload (recommended)
make dev
# Requires air: go install github.com/air-verse/air@latest

# Run without live reload
make run-stdio

# Run tests
make test

# Format code
make fmt

# Lint code
make lint

# Install all dev tools
make install-tools

# Clean build artifacts
make clean

Live Reload

Install air for automatic rebuilds:

bash

go install github.com/air-verse/air@latest
make dev

Changes to any `.go` file will automatically rebuild and restart the server.

🔍 MCP Inspector

The MCP Inspector is an essential development tool for testing and debugging MCP servers.

Running Inspector

bash

npx @modelcontextprotocol/inspector -- go run ./cmd/stdio/main.go

What Inspector Provides

Tools Tab: List and invoke all registered tools with parameters
Resources Tab: Browse and read resources and templates
Prompts Tab: View and test prompt templates
Logs Tab: See JSON-RPC messages between client and server
Schema Validation: Verify tool input/output schemas

Debugging Tips

1. Start Inspector before connecting your IDE/client

2. Use the "Logs" tab to see exact request/response payloads

3. Test tool annotations (ToolAnnotations) are exposed correctly

4. Verify progress notifications appear for `long_task`

5. Check that sampling works with `ask_llm`

📖 Feature Examples

Tool with Annotations

mcp.AddTool(server, &mcp.Tool{
    Name:        "hello",
    Title:       "Say Hello",
    Description: "A friendly greeting tool",
    Annotations: &mcp.ToolAnnotations{
        ReadOnlyHint: ptr(true),
    },
}, helloHandler)

func helloHandler(ctx context.Context, req *mcp.CallToolRequest, input helloInput) (*mcp.CallToolResult, any, error) {
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: fmt.Sprintf("Hello, %s!", input.Name)},
        },
    }, nil, nil
}

Resource Template

server.AddResourceTemplate(&mcp.ResourceTemplate{
    Name:        "Personalized Greeting",
    URITemplate: "greeting://{name}",
    MIMEType:    "text/plain",
}, greetingHandler)

Tool with Progress Updates

func longTaskHandler(ctx context.Context, req *mcp.CallToolRequest, input longTaskInput) (*mcp.CallToolResult, any, error) {
    progressToken := req.Params.GetProgressToken()
    
    for i := 0; i < 5; i++ {
        req.Session.NotifyProgress(ctx, &mcp.ProgressNotificationParams{
            ProgressToken: progressToken,
            Progress:      float64(i) / 5.0,
            Total:         1.0,
        })
        time.Sleep(time.Second)
    }
    
    return &mcp.CallToolResult{
        Content: []mcp.Content{&mcp.TextContent{Text: "Done!"}},
    }, nil, nil
}

Tool with Sampling

result, err := req.Session.CreateMessage(ctx, &mcp.CreateMessageParams{
    Messages: []*mcp.SamplingMessage{
        {Role: "user", Content: &mcp.TextContent{Text: prompt}},
    },
    MaxTokens: 100,
})

🔐 Environment Variables

Copy `.env.example` to `.env` and configure:

bash

cp .env.example .env

Variable	Description	Default
`PORT`	HTTP server port	`3000`

🤝 Contributing

Contributions welcome! Please ensure your changes maintain feature parity with other language starters.

📄 License

MIT License - see LICENSE for details.

Frequently asked questions

What is mcp-go-starter?

mcp-go-starter is A starter repo for building a go MCP server

How do I install mcp-go-starter?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is mcp-go-starter open source?

Yes — it is hosted on GitHub at https://github.com/SamMorrowDrums/mcp-go-starter and has 6 stars.

Related MCP tools

mcp-link

Convert Any OpenAPI V3 API to MCP Server Go-based implementation. Trusted by 500+ developers. Trusted by 500+ developers.

568 Go

agentsmcpmcp-server

localai

:robot: The free, Open Source alternative to OpenAI, Claude and others. Self-hosted and local-first. Drop-in replacement for OpenAI, running on consumer-gra...

36,790 Go

aiapiaudio-generation+17