mcp-golang

mcp-golang 是 Model Context Protocol 的一个非官方 Go 实现。

只需几行代码，即可用 Go 编写 MCP 服务器和客户端。

文档请访问 https://mcpgolang.com

亮点

• 🛡️类型安全 - 将工具参数定义为原生 Go 结构体，其余工作由 mcp-golang 自动完成。自动模式生成、反序列化、错误处理等。
• 🚛 自定义传输层 - 可使用内置传输层（stdio 提供完整功能支持，HTTP 用于无状态通信）或编写自己的传输层。
• ⚡ 低样板代码 - mcp-golang 会为您生成所有 MCP 端点，您只需关注工具、提示和资源。
• 🧩 模块化 - 该库分为三个组件：传输层、协议层和服务器/客户端层。您可以全部使用，也可以只取所需部分。
• 🔄 双向通信 - 通过 stdio 传输层完全支持服务器端和客户端实现。

使用示例

通过 go get github.com/metoro-io/mcp-golang 安装。

服务器示例

package main

import (
	"fmt"
	"github.com/metoro-io/mcp-golang"
	"github.com/metoro-io/mcp-golang/transport/stdio"
)

// 工具参数仅为结构体，并添加 jsonschema 标签
// 更多信息请参见 https://mcpgolang.com/tools#schema-generation
type Content struct {
	Title       string  `json:"title" jsonschema:"required,description=要提交的标题"`
	Description *string `json:"description" jsonschema:"description=要提交的描述"`
}
type MyFunctionsArguments struct {
	Submitter string  `json:"submitter" jsonschema:"required,description=调用此工具的实体名称（openai、google、claude 等）"`
	Content   Content `json:"content" jsonschema:"required,description=消息内容"`
}

func main() {
	done := make(chan struct{})

	server := mcp_golang.NewServer(stdio.NewStdioServerTransport())
	err := server.RegisterTool("hello", "向某人问好", func(arguments MyFunctionsArguments) (*mcp_golang.ToolResponse, error) {
		return mcp_golang.NewToolResponse(mcp_golang.NewTextContent(fmt.Sprintf("你好，%server！", arguments.Submitter))), nil
	})
	if err != nil {
		panic(err)
	}

	err = server.RegisterPrompt("promt_test", "这是一个测试提示", func(arguments Content) (*mcp_golang.PromptResponse, error) {
		return mcp_golang.NewPromptResponse("description", mcp_golang.NewPromptMessage(mcp_golang.NewTextContent(fmt.Sprintf("你好，%server！", arguments.Title)), mcp_golang.RoleUser)), nil
	})
	if err != nil {
		panic(err)
	}

	err = server.RegisterResource("test://resource", "resource_test", "这是一个测试资源", "application/json", func() (*mcp_golang.ResourceResponse, error) {
		return mcp_golang.NewResourceResponse(mcp_golang.NewTextEmbeddedResource("test://resource", "这是一个测试资源", "application/json")), nil
	})

	err = server.Serve()
	if err != nil {
		panic(err)
	}

	<-done
}

HTTP 服务器示例

您也可以使用标准 HTTP 传输层或 Gin 框架创建基于 HTTP 的服务器：

// 标准 HTTP
transport := http.NewHTTPTransport("/mcp")
transport.WithAddr(":8080")
server := mcp_golang.NewServer(transport)

// 或使用 Gin 框架
transport := http.NewGinTransport()
router := gin.Default()
router.POST("/mcp", transport.Handler())
server := mcp_golang.NewServer(transport)

注意：HTTP 传输层是无状态的，不支持通知等双向功能。如需这些功能，请使用 stdio 传输层。

客户端示例

更多完整示例请查看 examples/client 目录。

package main

import (
    "context"
    "log"
    mcp "github.com/metoro-io/mcp-golang"
    "github.com/metoro-io/mcp-golang/transport/stdio"
)

// 定义类型安全的参数
type CalculateArgs struct {
    Operation string `json:"operation"`
    A         int    `json:"a"`
    B         int    `json:"b"`
}

func main() {
   cmd := exec.Command("go", "run", "./server/main.go")
   stdin, err := cmd.StdinPipe()
   if err != nil {
    log.Fatalf("无法获取标准输入管道： %v", err)
   }
   stdout, err := cmd.StdoutPipe()
   if err != nil {
    log.Fatalf("无法获取标准输出管道： %v", err)
   }

   if err := cmd.Start(); err != nil {
    log.Fatalf("无法启动服务器： %v", err)
   }
   defer cmd.Process.Kill()
    // 创建并初始化客户端
    transport := stdio.NewStdioServerTransportWithIO(stdout, stdin)
    client := mcp.NewClient(transport)
    
    if _, err := client.Initialize(context.Background()); err != nil {
        log.Fatalf("初始化失败： %v", err)
    }

    // 使用类型化参数调用工具
    args := CalculateArgs{
        Operation: "add",
        A:         10,
        B:         5,
    }
    
    response, err := client.CallTool(context.Background(), "calculate", args)
    if err != nil {
        log.Fatalf("调用工具失败： %v", err)
    }
    
    if response != nil && len(response.Content) > 0 {
        log.Printf("结果： %s", response.Content[0].TextContent.Text)
    }
}

与 Claude Desktop 集成

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中创建文件，内容如下：

{
"mcpServers": {
  "golang-mcp-server": {
      "command": "<您的 Go MCP 服务器可执行文件路径>",
      "args": [],
      "env": {}
    }
  }
}

贡献

我们非常欢迎贡献！请查看我们的贡献指南。

Discord

有任何建议或关于 API 和使用的问题吗？请在 Discord 服务器 上提问。维护人员将很乐意为您提供帮助。

示例

在此处可以找到使用该库的更多详细示例：

• Metoro - 查询并与由 Metoro 监控的 Kubernetes 环境交互

欢迎提交 PR 来添加您自己的项目！

服务器功能实现

工具

• 工具调用
• 将原生 Go 结构体作为参数
• 自动生成的工具列表端点
• 变更通知
• 分页

提示词

• 提示词调用
• 自动生成的提示词列表端点
• 变更通知
• 分页

资源

• 资源调用
• 自动生成的资源列表端点
• 变更通知
• 分页

传输协议

• Stdio - 完全支持所有功能，包括双向通信
• HTTP - 适用于简单请求-响应场景的无状态传输（不支持通知）
• Gin - 集成 Gin 框架的 HTTP 传输（无状态，不支持通知）
• SSE
• 自定义传输协议支持
• HTTPS 并支持自定义认证 - 正在开发中。目前不在规范范围内，但我们将为其添加实验性支持。

客户端

• 调用工具
• 调用提示词
• 调用资源
• 列出工具
• 列出提示词
• 列出资源

mcp-golang 快速上手指南

mcp-golang 是一个用 Go 语言实现的非官方 Model Context Protocol (MCP) 库。它允许开发者通过极少的代码编写 MCP 服务端和客户端，支持类型安全的参数定义、自动 Schema 生成以及多种传输协议。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Go 版本: 建议安装 Go 1.21 或更高版本
• 依赖管理: 确保已初始化 Go Module (go mod init)

无需其他特殊的前置依赖，库会自动处理 JSON Schema 生成和序列化逻辑。

安装步骤

使用 go get 命令将库添加到你的项目中：

go get github.com/metoro-io/mcp-golang

基本使用

1. 创建 MCP 服务端 (Server)

以下示例展示如何创建一个基于 stdio 传输的简单服务器，注册一个工具（Tool）、一个提示词（Prompt）和一个资源（Resource）。

特点：

• 使用原生 Go struct 定义参数，自动处理验证和文档生成。
• 极低样板代码，只需关注业务逻辑。

package main

import (
	"fmt"
	"github.com/metoro-io/mcp-golang"
	"github.com/metoro-io/mcp-golang/transport/stdio"
)

// 定义工具参数结构体，使用 jsonschema 标签进行描述
type Content struct {
	Title       string  `json:"title" jsonschema:"required,description=The title to submit"`
	Description *string `json:"description" jsonschema:"description=The description to submit"`
}

type MyFunctionsArguments struct {
	Submitter string  `json:"submitter" jsonschema:"required,description=The name of the thing calling this tool (openai, google, claude, etc)"`
	Content   Content `json:"content" jsonschema:"required,description=The content of the message"`
}

func main() {
	done := make(chan struct{})

	// 初始化服务器，使用 stdio 传输协议
	server := mcp_golang.NewServer(stdio.NewStdioServerTransport())

	// 注册工具 (Tool)
	err := server.RegisterTool("hello", "Say hello to a person", func(arguments MyFunctionsArguments) (*mcp_golang.ToolResponse, error) {
		return mcp_golang.NewToolResponse(mcp_golang.NewTextContent(fmt.Sprintf("Hello, %s!", arguments.Submitter))), nil
	})
	if err != nil {
		panic(err)
	}

	// 注册提示词 (Prompt)
	err = server.RegisterPrompt("promt_test", "This is a test prompt", func(arguments Content) (*mcp_golang.PromptResponse, error) {
		return mcp_golang.NewPromptResponse("description", mcp_golang.NewPromptMessage(mcp_golang.NewTextContent(fmt.Sprintf("Hello, %s!", arguments.Title)), mcp_golang.RoleUser)), nil
	})
	if err != nil {
		panic(err)
	}

	// 注册资源 (Resource)
	err = server.RegisterResource("test://resource", "resource_test", "This is a test resource", "application/json", func() (*mcp_golang.ResourceResponse, error) {
		return mcp_golang.NewResourceResponse(mcp_golang.NewTextEmbeddedResource("test://resource", "This is a test resource", "application/json")), nil
	})
	if err != nil {
		panic(err)
	}

	// 启动服务
	err = server.Serve()
	if err != nil {
		panic(err)
	}

	<-done
}

2. 创建 HTTP 服务端 (可选)

如果你需要无状态的 HTTP 通信（不支持双向通知），可以使用内置的 HTTP 传输或 Gin 框架集成：

// 标准 HTTP 传输
transport := http.NewHTTPTransport("/mcp")
transport.WithAddr(":8080")
server := mcp_golang.NewServer(transport)

// 或者使用 Gin 框架
// transport := http.NewGinTransport()
// router := gin.Default()
// router.POST("/mcp", transport.Handler())
// server := mcp_golang.NewServer(transport)

3. 创建 MCP 客户端 (Client)

以下示例展示如何通过 stdio 启动一个子进程作为服务器，并作为客户端调用其工具。

package main

import (
    "context"
    "log"
    "os/exec"
    mcp "github.com/metoro-io/mcp-golang"
    "github.com/metoro-io/mcp-golang/transport/stdio"
)

// 定义类型安全的参数
type CalculateArgs struct {
    Operation string `json:"operation"`
    A         int    `json:"a"`
    B         int    `json:"b"`
}

func main() {
   // 启动本地服务器进程
   cmd := exec.Command("go", "run", "./server/main.go")
   stdin, err := cmd.StdinPipe()
   if err != nil {
    log.Fatalf("Failed to get stdin pipe: %v", err)
   }
   stdout, err := cmd.StdoutPipe()
   if err != nil {
    log.Fatalf("Failed to get stdout pipe: %v", err)
   }

   if err := cmd.Start(); err != nil {
    log.Fatalf("Failed to start server: %v", err)
   }
   defer cmd.Process.Kill()

    // 创建并初始化客户端
    transport := stdio.NewStdioServerTransportWithIO(stdout, stdin)
    client := mcp.NewClient(transport)
    
    if _, err := client.Initialize(context.Background()); err != nil {
        log.Fatalf("Failed to initialize: %v", err)
    }

    // 调用工具
    args := CalculateArgs{
        Operation: "add",
        A:         10,
        B:         5,
    }
    
    response, err := client.CallTool(context.Background(), "calculate", args)
    if err != nil {
        log.Fatalf("Failed to call tool: %v", err)
    }
    
    if response != nil && len(response.Content) > 0 {
        log.Printf("Result: %s", response.Content[0].TextContent.Text)
    }
}

4. 集成到 Claude Desktop

若要在 Claude Desktop 中使用你编写的 Go 服务器，请在配置文件 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或对应路径下添加以下内容：

{
"mcpServers": {
  "golang-mcp-server": {
      "command": "<your path to golang MCP server go executable>",
      "args": [],
      "env": {}
    }
  }
}

注意：请将 <your path to golang MCP server go executable> 替换为你编译后的可执行文件的绝对路径。