Skip to content
Back to search

mcp-golang

Write Model Context Protocol servers in few lines of go code. Docs at https://mcpgolang.com . Created by https://metoro.io

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/metoro-io--mcp-golang/badge.svg)](/listings/metoro-io--mcp-golang)

HTML

<a href="/listings/metoro-io--mcp-golang"><img src="/api/listings/metoro-io--mcp-golang/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 245 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="./resources/mcp-golang-logo.webp" height="300" alt="Statusphere logo">
  3. </div>
  4. <br/>
  5. <div align="center">
  6. ![GitHub stars](https://img.shields.io/github/stars/metoro-io/mcp-golang?style=social)
  7. ![GitHub forks](https://img.shields.io/github/forks/metoro-io/mcp-golang?style=social)
  8. ![GitHub issues](https://img.shields.io/github/issues/metoro-io/mcp-golang)
  9. ![GitHub pull requests](https://img.shields.io/github/issues-pr/metoro-io/mcp-golang)
  10. ![GitHub license](https://img.shields.io/github/license/metoro-io/mcp-golang)
  11. ![GitHub contributors](https://img.shields.io/github/contributors/metoro-io/mcp-golang)
  12. ![GitHub last commit](https://img.shields.io/github/last-commit/metoro-io/mcp-golang)
  13. [![GoDoc](https://pkg.go.dev/badge/github.com/metoro-io/mcp-golang.svg)](https://pkg.go.dev/github.com/metoro-io/mcp-golang)
  14. [![Go Report Card](https://goreportcard.com/badge/github.com/metoro-io/mcp-golang)](https://goreportcard.com/report/github.com/metoro-io/mcp-golang)
  15. ![Tests](https://github.com/metoro-io/mcp-golang/actions/workflows/go-test.yml/badge.svg)
  16. </div>
  17. # mcp-golang
  18. mcp-golang is an unofficial implementation of the [Model Context Protocol](https://modelcontextprotocol.io/) in Go.
  19. Write MCP servers and clients in golang with a few lines of code.
  20. Docs at [https://mcpgolang.com](https://mcpgolang.com)
  21. ## Highlights
  22. - 🛡️**Type safety** - Define your tool arguments as native go structs, have mcp-golang handle the rest. Automatic schema generation, deserialization, error handling etc.
  23. - 🚛 **Custom transports** - Use the built-in transports (stdio for full feature support, HTTP for stateless communication) or write your own.
  24. - ⚡ **Low boilerplate** - mcp-golang generates all the MCP endpoints for you apart from your tools, prompts and resources.
  25. - 🧩 **Modular** - The library is split into three components: transport, protocol and server/client. Use them all or take what you need.
  26. - 🔄 **Bi-directional** - Full support for both server and client implementations through stdio transport.
  27. ## Example Usage
  28. Install with `go get github.com/metoro-io/mcp-golang`
  29. ### Server Example
  30. ```go
  31. package main
  32. import (
  33. "fmt"
  34. "github.com/metoro-io/mcp-golang"
  35. "github.com/metoro-io/mcp-golang/transport/stdio"
  36. )
  37. // Tool arguments are just structs, annotated with jsonschema tags
  38. // More at https://mcpgolang.com/tools#schema-generation
  39. type Content struct {
  40. Title string `json:"title" jsonschema:"required,description=The title to submit"`
  41. Description *string `json:"description" jsonschema:"description=The description to submit"`
  42. }
  43. type MyFunctionsArguments struct {
  44. Submitter string `json:"submitter" jsonschema:"required,description=The name of the thing calling this tool (openai, google, claude, etc)"`
  45. Content Content `json:"content" jsonschema:"required,description=The content of the message"`
  46. }
  47. func main() {
  48. done := make(chan struct{})
  49. server := mcp_golang.NewServer(stdio.NewStdioServerTransport())
  50. err := server.RegisterTool("hello", "Say hello to a person", func(arguments MyFunctionsArguments) (*mcp_golang.ToolResponse, error) {
  51. return mcp_golang.NewToolResponse(mcp_golang.NewTextContent(fmt.Sprintf("Hello, %server!", arguments.Submitter))), nil
  52. })
  53. if err != nil {
  54. panic(err)
  55. }
  56. err = server.RegisterPrompt("promt_test", "This is a test prompt", func(arguments Content) (*mcp_golang.PromptResponse, error) {
  57. return mcp_golang.NewPromptResponse("description", mcp_golang.NewPromptMessage(mcp_golang.NewTextContent(fmt.Sprintf("Hello, %server!", arguments.Title)), mcp_golang.RoleUser)), nil
  58. })
  59. if err != nil {
  60. panic(err)
  61. }
  62. err = server.RegisterResource("test://resource", "resource_test", "This is a test resource", "application/json", func() (*mcp_golang.ResourceResponse, error) {
  63. return mcp_golang.NewResourceResponse(mcp_golang.NewTextEmbeddedResource("test://resource", "This is a test resource", "application/json")), nil
  64. })
  65. err = server.Serve()
  66. if err != nil {
  67. panic(err)
  68. }
  69. <-done
  70. }
  71. ```
  72. ### HTTP Server Example
  73. You can also create an HTTP-based server using either the standard HTTP transport or Gin framework:
  74. ```go
  75. // Standard HTTP
  76. transport := http.NewHTTPTransport("/mcp")
  77. transport.WithAddr(":8080")
  78. server := mcp_golang.NewServer(transport)
  79. // Or with Gin framework
  80. transport := http.NewGinTransport()
  81. router := gin.Default()
  82. router.POST("/mcp", transport.Handler())
  83. server := mcp_golang.NewServer(transport)
  84. ```
  85. Note: HTTP transports are stateless and don't support bidirectional features like notifications. Use stdio transport if you need those features.
  86. ### Client Example
  87. Checkout the [examples/client](./examples/client) directory for a more complete example.
  88. ```go
  89. package main
  90. import (
  91. "context"
  92. "log"
  93. mcp "github.com/metoro-io/mcp-golang"
  94. "github.com/metoro-io/mcp-golang/transport/stdio"
  95. )
  96. // Define type-safe arguments
  97. type CalculateArgs struct {
  98. Operation string `json:"operation"`
  99. A int `json:"a"`
  100. B int `json:"b"`
  101. }
  102. func main() {
  103. cmd := exec.Command("go", "run", "./server/main.go")
  104. stdin, err := cmd.StdinPipe()
  105. if err != nil {
  106. log.Fatalf("Failed to get stdin pipe: %v", err)
  107. }
  108. stdout, err := cmd.StdoutPipe()
  109. if err != nil {
  110. log.Fatalf("Failed to get stdout pipe: %v", err)
  111. }
  112. if err := cmd.Start(); err != nil {
  113. log.Fatalf("Failed to start server: %v", err)
  114. }
  115. defer cmd.Process.Kill()
  116. // Create and initialize client
  117. transport := stdio.NewStdioServerTransportWithIO(stdout, stdin)
  118. client := mcp.NewClient(transport)
  119. if _, err := client.Initialize(context.Background()); err != nil {
  120. log.Fatalf("Failed to initialize: %v", err)
  121. }
  122. // Call a tool with typed arguments
  123. args := CalculateArgs{
  124. Operation: "add",
  125. A: 10,
  126. B: 5,
  127. }
  128. response, err := client.CallTool(context.Background(), "calculate", args)
  129. if err != nil {
  130. log.Fatalf("Failed to call tool: %v", err)
  131. }
  132. if response != nil && len(response.Content) > 0 {
  133. log.Printf("Result: %s", response.Content[0].TextContent.Text)
  134. }
  135. }
  136. ```
  137. ### Using with Claude Desktop
  138. Create a file in ~/Library/Application Support/Claude/claude_desktop_config.json with the following contents:
  139. ```json
  140. {
  141. "mcpServers": {
  142. "golang-mcp-server": {
  143. "command": "<your path to golang MCP server go executable>",
  144. "args": [],
  145. "env": {}
  146. }
  147. }
  148. }
  149. ```
  150. ## Contributions
  151. Contributions are more than welcome! Please check out [our contribution guidelines](./CONTRIBUTING.md).
  152. ## Discord
  153. Got any suggestions, have a question on the api or usage? Ask on the [discord server](https://discord.gg/33saRwE3pT).
  154. A maintainer will be happy to help you out.
  155. ## Examples
  156. Some more extensive examples using the library found here:
  157. - <img height="12" width="12" src="https://metoro.io/static/images/logos/Metoro.svg" /> **[Metoro](https://github.com/metoro-io/metoro-mcp-server)** - Query and interact with kubernetes environments monitored by Metoro
  158. Open a PR to add your own projects!
  159. ## Server Feature Implementation
  160. ### Tools
  161. - [x] Tool Calls
  162. - [x] Native go structs as arguments
  163. - [x] Programatically generated tool list endpoint
  164. - [x] Change notifications
  165. - [x] Pagination
  166. ### Prompts
  167. - [x] Prompt Calls
  168. - [x] Programatically generated prompt list endpoint
  169. - [x] Change notifications
  170. - [x] Pagination
  171. ### Resources
  172. - [x] Resource Calls
  173. - [x] Programatically generated resource list endpoint
  174. - [x] Change notifications
  175. - [x] Pagination
  176. ### Transports
  177. - [x] Stdio - Full support for all features including bidirectional communication
  178. - [x] HTTP - Stateless transport for simple request-response scenarios (no notifications support)
  179. - [x] Gin - HTTP transport with Gin framework integration (stateless, no notifications support)
  180. - [x] SSE
  181. - [x] Custom transport support
  182. - [ ] HTTPS with custom auth support - in progress. Not currently part of the spec but we'll be adding experimental support for it.
  183. ### Client
  184. - [x] Call tools
  185. - [x] Call prompts
  186. - [x] Call resources
  187. - [x] List tools
  188. - [x] List prompts
  189. - [x] List resources

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.