kioie/tiny-go-mcp-server

A lightweight **Model Context Protocol (MCP)** toolkit for Go. Build spec-compliant MCP servers (stdio, streamable HTTP, legacy SSE) with tools, resources, and prompts — minimal boilerplate and automatic JSON Schema from Go structs.
Built on the official modelcontextprotocol/go-sdk.
**Requirements:** Go 1.26+ (download).
---
Why Tiny?
| | Tiny Go MCP Server | Full frameworks |
|---|---|---|
| **Goal** | Thin helper on official go-sdk + tiny static binary | Full MCP feature surface |
| **Deps** | Official go-sdk only | Varies |
| **Binary** | ~5MB stripped, no runtime on host | Often larger stacks |
| **Schemas** | Inferred from struct tags | Manual or builder APIs |
Use this project as a **library** (tinymcp package) or as a **starting template** (cmd/tiny-go-mcp).
When to use what
| | **tinymcp** (this repo) | **mcp-go** | **go-sdk** alone |
|---|---|---|---|
| **Best for** | Thin helper on go-sdk, tiny binary | Rich helpers, large ecosystem | Full control, no extra layer |
| **Schema** | Struct tags → auto JSON Schema | Builder APIs / helpers | AddTool + generics yourself |
| **Transport** | stdio (Start()), streamable HTTP (StartHTTP), legacy SSE (StartSSE) | stdio, SSE, HTTP, … | All transports |
| **Deps** | go-sdk only | Standalone module | go-sdk only |
Choose **tinymcp** when you want the official protocol implementation with minimal boilerplate and a small static server binary.
Philosophy
**tinymcp is a thin helper on the official go-sdk — not a replacement for it.**
We reduce setup and transport boilerplate (server creation, registration error handling, stdio/HTTP/SSE, TextResult, deploy examples). The protocol implementation, generics, and schema inference still come from modelcontextprotocol/go-sdk.
That means handler code uses **both** imports — and that is intentional:
| Use **tinymcp** for | Use **go-sdk** (mcp) for |
|---------------------|----------------------------|
| NewServer, RegisterTool, transports | Handler signatures (CallToolRequest, GetPromptRequest, …) |
| Safe registration (errors, not panics) | Tool annotations, elicitation, custom protocol features |
| TextResult, HTTP middleware helpers | Anything via server.RawServer() |
We are **not** aiming for a non-leaky facade that hides the SDK. If you need full control, call RawServer() or use go-sdk directly — same underlying server, no lock-in.
tinymcp vs raw go-sdk
Same protocol implementation — tinymcp removes repetitive setup. Handler code still imports mcp for request types in both cases.
**go-sdk alone** (minimal stdio server):
**tinymcp** (same tool, less boilerplate):
| tinymcp adds | Still on go-sdk (mcp) |
|--------------|-------------------------|
| NewServer(name, ver) | Handler signatures (CallToolRequest, prompts, resources) |
| RegisterTool + struct-tag JSON Schema | Tool annotations via RegisterToolDef + mcp.Tool |
| Safe registration errors (no panics) | Advanced session / event-store APIs |
| Start() / StartHTTP() / HTTP middleware | Full control via RawServer() |
Use **go-sdk alone** when you want zero wrapper. Use **tinymcp** when you want less setup while staying on the official implementation.
Transport
| Method | API | Typical clients |
|--------|-----|-----------------|
| **stdio** (default) | Start() | Cursor, Claude Desktop, Windsurf (local subprocess) |
| **Streamable HTTP** | StartHTTP(addr, opts) or StreamableHTTPHandler | Remote MCP clients, gateways, browser tools |
| **Legacy SSE** | StartSSE(addr, opts) or SSEHandler | Older clients on MCP 2024-11-05 SSE transport |
Start() runs **stdio** (stdin/stdout) — what most local AI clients expect.
For HTTP/SSE, tinymcp wraps the official go-sdk handlers with minimal options: