Gomcp

gomcp

Production-ready Model Context Protocol (MCP) server template in Go

Features | Quick Start | Use as Template | Documentation | Contributing

---

Overview

gomcp is a complete, production-ready MCP server template built with Go and the official MCP Go SDK. It implements the full MCP 2025-06-18 specification and is designed to be used as a starting point for building your own MCP servers.

Why gomcp?

• Complete Implementation - All 12 MCP features fully implemented
• Production Ready - Docker support, CI/CD, security best practices
• Well Documented - Comprehensive docs, examples, and customization guide
• Easy to Customize - Clean architecture, modular design, extensive comments
• Multiple Transports - HTTP/SSE for Cursor IDE, stdio for Claude Desktop

Features

MCP Features (12/12)

| Feature | Status | Description | |---------|:------:|-------------| | Tools | Yes | 4 example tools with structured outputs | | Prompts | Yes | 3 reusable prompt templates | | Resources | Yes | 6 static/dynamic resources | | Roots | Yes | Filesystem root definitions | | Completion | Yes | Structured outputs with JSON schemas | | Logging | Yes | Server-to-client notifications (8 levels) | | Pagination | Yes | Cursor-based pagination | | Sampling | Yes | Server-to-client LLM requests | | Elicitation | Yes | Server-to-user data requests | | Progress | Yes | Real-time progress notifications | | Cancellation | Yes | Request cancellation support | | Ping | Yes | Health checks |

Infrastructure

| Feature | Description | |---------|-------------| | Multi-Transport | HTTP/SSE + stdio support | | Cursor Compatible | First-class Cursor IDE support | | Claude Desktop | stdio transport for local use | | Docker Ready | Multi-stage Dockerfile included | | CI/CD | GitHub Actions workflows | | Hot Reload | Development mode with air | | OAuth Support | Authentication ready | | Metrics | Built-in monitoring endpoints | | Security | Non-root containers, SSL/TLS |

Quick Start

Prerequisites

• Go 1.24+
• (Optional) Docker/Podman

Installation

# Clone the repository
git clone https://github.com/NP-compete/gomcp.git
cd gomcp

# Download dependencies
go mod download

# Build and run
make run

Running the Server

For Cursor IDE (HTTP/SSE)

make cursor
# Server runs on http://localhost:8081/mcp/sse

Configure ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gomcp": {
      "url": "http://localhost:8081/mcp/sse"
    }
  }
}

Restart Cursor IDE to connect.

For Claude Desktop (stdio)

# Build the binary
make build-prod

# Configure Claude Desktop
# ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
# %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "gomcp": {
      "command": "/absolute/path/to/gomcp/bin/gomcp",
      "args": [],
      "env": {
        "MCP_TRANSPORT_PROTOCOL": "stdio"
      }
    }
  }
}

Restart Claude Desktop to connect.

With Docker

# Build and run with Docker
make docker-build
make docker-run

# Or with Docker Compose
docker-compose up -d

Use as Template

This repository is designed to be used as a template for your own MCP server.

Option 1: GitHub Template (Recommended)

Click the "Use this template" button on GitHub to create a new repository.

Option 2: Manual Clone

# Clone and remove git history
git clone https://github.com/NP-compete/gomcp.git my-mcp-server
cd my-mcp-server
rm -rf .git
git init

# Update module name
# Edit go.mod: module github.com/YOUR_USERNAME/my-mcp-server
# Then update all imports

Customization Guide

See [docs/CUSTOMIZATION.md](docs/CUSTOMIZATION.md) for detailed instructions on:

• Adding your own tools, prompts, and resources
• Configuring authentication
• Customizing the Docker setup
• Setting up CI/CD for your repository

Project Structure

gomcp/
├── cmd/server/          # Application entry point
├── internal/
│   ├── api/            # HTTP handlers & routing
│   ├── completion/     # Structured outputs
│   ├── config/         # Configuration management
│   ├── logging/        # Server-to-client logs
│   ├── mcp/            # MCP server logic
│   ├── pagination/     # Cursor-based pagination
│   ├── prompts/        # Prompt implementations
│   ├── resources/      # Resource implementations
│   ├── roots/          # Filesystem roots
│   └── tools/          # Tool implementations
├── pkg/mcpprotocol/    # MCP protocol types
├── test/               # Integration tests
├── docs/               # Documentation
├── scripts/            # Utility scripts
├── .github/            # GitHub Actions & templates
├── Dockerfile          # Container build
├── docker-compose.yml  # Local development
└── Makefile           # Build commands

Configuration

| Variable | Default | Description | |----------|---------|-------------| | MCP_TRANSPORT_PROTOCOL | http | Transport: stdio, http, sse | | MCP_PORT | 8081 | Server port | | CURSOR_COMPATIBLE_SSE | true | Enable Cursor compatibility | | ENABLE_AUTH | true | Enable OAuth authentication | | LOG_LEVEL | INFO | Log level |

See [.env.example](.env.example) for all options.

Testing

# Run all tests
make test

# Run with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run linter
make lint

# Run security scan
make security-scan

Documentation

| Document | Description | |----------|-------------| | [Architecture](docs/ARCHITECTURE.md) | System design and component overview | | [Customization](docs/CUSTOMIZATION.md) | Guide to customizing the template | | [Contributing](CONTRIBUTING.md) | How to contribute | | [Security](SECURITY.md) | Security policy |

External Resources

• MCP Specification
• Official Go SDK

Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Acknowledgments

• Model Context Protocol - The MCP specification
• Official Go SDK - The foundation of this server
• All contributors who help improve this project

---

Built for the MCP community

Star us on GitHub | Report Bug | Discussions

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NP-compete
• Source: NP-compete/gomcp
• License: MIT

Install and usage instructions live in the source repository linked above.