raythurman2386/go-mcp-template

Go MCP Server

A template for building Model Context Protocol (MCP) servers in Go. This project provides a simple HTTP server that exposes tools for Large Language Models (LLMs) to consume.

Features

• 🚀 Simple HTTP-based MCP server
• 🛠️ Extensible tool system
• 🐳 Docker support
• 🔐 API key authentication
• ⚡ Concurrent tool execution with timeout handling
• 📝 Well-documented API

Prerequisites

• Go 1.22 or later
• Docker (optional, for containerized deployment)

Quick Start

1. Clone the repository

   git clone https://github.com/raythurman2386/go-mcp-template.git
   cd go-mcp-template
   

2. Update the module name Edit go.mod and replace example.com/m with your module path:

   module github.com/raythurman2386/go-mcp-template
   

3. Build and run

   # Build the server
   go build -o mcp-server ./cmd/mcp-server
   
   # Set your API key and run
   export MCP_API_KEY="your-secret-key"
   ./mcp-server
   

The server will start on http://localhost:8080.

Docker Deployment

# Build the image
docker build -t mcp-server .

# Run the container
docker run -d -p 8080:8080 -e MCP_API_KEY="your-secret-key" --name mcp-server mcp-server

API Documentation

Authentication

All requests require an X-API-Key header with your API key:

curl -X POST http://localhost:8080/tool \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "hello", "parameters": {"name": "World"}}'

Endpoints

POST /tool

Execute a tool with the given parameters.

Request Body:

{
  "tool_name": "hello",
  "parameters": {
    "name": "World"
  }
}

Success Response (200):

{
  "result": "Hello, World!"
}

Error Response (400/404/408/500):

{
  "error": "error message"
}

Available Tools

hello

Returns a personalized greeting.

Parameters:

• name (string, required): The name to greet

Example:

{
  "tool_name": "hello",
  "parameters": {
    "name": "Alice"
  }
}

Response:

{
  "result": "Hello, Alice!"
}

Configuration

Project Structure

.
├── cmd/
│   └── mcp-server/          # Main application entry point
│       ├── main.go         # Server startup and routing
│       └── main_test.go    # Server tests
├── pkg/
│   ├── api/                # API types and structures
│   │   └── types.go
│   └── tool/               # Tool implementations
│       ├── tool.go         # Tool manager and interface
│       ├── hello.go        # Hello tool implementation
│       ├── tool_test.go    # Tool tests
│       └── hello_test.go   # Hello tool tests
├── Dockerfile              # Docker build configuration
├── go.mod                  # Go module definition
├── go.sum                  # Go module checksums
└── README.md              # This file

Development

Adding New Tools

1. Create a new tool struct that implements the Tool interface:

   type MyTool struct{}
   
   func (t *MyTool) Execute(parameters map[string]interface{}) (string, error) {
       // Your tool logic here
       return "result", nil
   }
   

2. Register the tool in main.go:

   toolManager.RegisterTool("mytool", &MyTool{})
   

3. Add tests in the appropriate test file.

Running Tests

go test ./...

Building for Production

CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o mcp-server ./cmd/mcp-server

Contributing

We welcome contributions! Please see our for details.

License

This project is licensed under the MIT License - see the file for details.

Related Projects

• Model Context Protocol - The protocol specification
• MCP SDKs - Official MCP implementations