/ 目录 / 演练场 / mcp-go (SDK)
● 社区 mark3labs ⚡ 即开即用

mcp-go (SDK)

作者 mark3labs · mark3labs/mcp-go

构建 MCP server 的 Go SDK——极少样板代码、类型安全的工具定义,是野外半数生产级 Go MCP 的基础。

mcp-go 是 Model Context Protocol 事实上的 Go SDK。它处理传输层(stdio + SSE + streamable HTTP)、JSON-RPC 帧、工具/资源/prompt 注册及请求验证,让你专注于 MCP server 逻辑本身。GitHub 的 mcp-server、dbhub、k8s-mcp 等众多项目都在使用。

为什么要用

核心特性

实时演示

实际使用效果

mcp-go-mark3labs.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mcp-go-mark3labs": {
      "command": "go",
      "args": [
        "install",
        "github.com/mark3labs/mcp-go/cmd/example@latest"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mcp-go-mark3labs": {
      "command": "go",
      "args": [
        "install",
        "github.com/mark3labs/mcp-go/cmd/example@latest"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mcp-go-mark3labs": {
      "command": "go",
      "args": [
        "install",
        "github.com/mark3labs/mcp-go/cmd/example@latest"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mcp-go-mark3labs": {
      "command": "go",
      "args": [
        "install",
        "github.com/mark3labs/mcp-go/cmd/example@latest"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mcp-go-mark3labs",
      "command": "go",
      "args": [
        "install",
        "github.com/mark3labs/mcp-go/cmd/example@latest"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "mcp-go-mark3labs": {
      "command": {
        "path": "go",
        "args": [
          "install",
          "github.com/mark3labs/mcp-go/cmd/example@latest"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add mcp-go-mark3labs -- go install github.com/mark3labs/mcp-go/cmd/example@latest

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: mcp-go (SDK)

用 100 行以内的代码为公司 API 构建内部 MCP server

👤 想将内部工具暴露给 Claude 的公司 Go 开发者 ⏱ ~45 min intermediate

何时使用: 你有一个 Go 服务,想让 Claude 调用它,无需编写 OpenAPI schema。

前置条件
  • Go 1.21+ — 通过 brew 或 asdf 安装
步骤
  1. 搭建 server 骨架
    Create a new Go project. Add mcp-go and define one tool: search_orders(customer_id) that calls our internal /v1/orders API.✓ 已复制
    → main.go 约 50 行,构建干净
  2. 用 mcp-inspector 测试
    Run the server in stdio mode. Open mcp-inspector and verify the tool shows up.✓ 已复制
    → 工具可从 inspector 调用
  3. 在 Claude 中注册
    Add the binary to claude_desktop_config.json. Test from Claude with a real customer ID.✓ 已复制
    → API 的实时响应

结果: 内部 Go API 通过类型安全的 MCP 工具暴露给 Claude。

注意事项
  • 长运行调用阻塞 stdio — 超过 5 秒的调用改用 SSE 或 streamable HTTP 传输
搭配使用: mcp-python-sdk

在不影响 REST 客户端的情况下,将现有 REST API 迁移至 MCP

👤 在不强制迁移的前提下采用 MCP 的后端团队 ⏱ ~60 min intermediate

何时使用: 你希望 REST 和 MCP 在同一 handler 上共存。

步骤
  1. 提取 handler 逻辑
    Take the existing /api/v1/search handler. Extract the core function so both gin and mcp-go can call it.✓ 已复制
    → Handler 拆分——HTTP handler 委托给纯函数
  2. 封装为 MCP 工具
    Register the pure func as an mcp-go tool. Map URL params to tool inputs.✓ 已复制
    → 相同逻辑,两个接入面
  3. 单一二进制,双传输
    Build one binary that runs gin on :8080 and the MCP server over stdio when invoked with --mcp.✓ 已复制
    → 多模式二进制

结果: REST 和 MCP 从同一个 Go 二进制提供服务,共享核心逻辑。

通过 SSE 在公网上托管 MCP server

👤 发布公共 MCP 的开发者(如 git-mcp.io) ⏱ ~90 min advanced

何时使用: 你想让用户无需本地安装即可添加你的 MCP。

前置条件
  • 域名和 TLS — Caddy/nginx + Let's Encrypt
步骤
  1. 切换到 SSE 传输
    Convert the stdio server to SSE. Add CORS for the relevant origins.✓ 已复制
    → Server 接受 /sse 连接
  2. 添加用户级认证
    Validate Bearer token on each connection; reject unknown.✓ 已复制
    → 无效 token 返回 401,有效 token 正常响应
  3. 部署并测试
    Deploy to fly.io. Add the URL to Claude via mcp-remote.✓ 已复制
    → Claude 指向远程 URL 即可调用工具

结果: 带认证的公网 MCP server,可供用户使用。

注意事项
  • SSE 在负载均衡器后断开长连接 — 在负载均衡器上配置超过 5 分钟的空闲超时

组合

与其他 MCP 搭配,撬动十倍杠杆

mcp-go-mark3labs + mcp-python-sdk

同一项目中使用两种 SDK 服务不同接入面

mcp-go-mark3labs + mcp-registry

将构建好的 MCP 发布到官方注册表

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
AddTool name, description, handler server 启动时为每个工具调用一次 0
AddResource uri, name, handler 暴露一个可读资源 0
AddPrompt name, description, handler 暴露可复用的 prompt 0
ServeStdio () 本地 stdio 模式(最常见) 0
ServeSSE addr, opts 网络/远程模式 0

成本与限制

运行它的成本

API 配额
不适用——库
每次调用 Token 数
不适用
费用
免费(MIT 协议)
提示
锁定到特定次版本;API 在 2025 年已稳定,但次要变更仍会出现

安全

权限、密钥、影响范围

凭据存储: 由你的工具 handler 决定
数据出站: 由你的 handler 控制

故障排查

常见错误与修复

工具对 Claude 不可见

检查能力协商是否完成;工具必须在调用 ServeStdio 之前注册

验证: 使用 mcp-inspector 确认工具列表
stdio 消息格式错误

不要在 handler 中向 stdout 打印——那是 JSON-RPC 通道。日志请用 stderr。

SSE 空闲时断开

添加定期心跳;配置代理超时

替代方案

mcp-go (SDK) 对比其他方案

替代方案何时用它替代权衡
mcp-python-sdk (official)你用 Python 开发不同语言;两者都是一等公民
TypeScript SDK (official)Node/Bun 生态适合JS 优先;性能上限不如 Go

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills