Gin-MCP MCP server

Gin-MCP is a library that connects your existing Gin web applications to Model Context Protocol (MCP) clients like Cursor. It automatically transforms your Gin routes into MCP tools with minimal configuration, making your APIs instantly accessible to MCP-compatible clients.

Installation

Install the package using Go's package manager:

go get github.com/ckanthony/gin-mcp

Basic Usage

Setting up Gin-MCP requires just a few lines of code:

package main

import (
	"net/http"

	server "github.com/ckanthony/gin-mcp/"
	"github.com/gin-gonic/gin"
)

func main() {
	// Create your Gin engine
	r := gin.Default()

	// Define your API routes as usual
	r.GET("/ping", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"message": "pong"})
	})

	r.GET("/users/:id", func(c *gin.Context) {
		userID := c.Param("id")
		c.JSON(http.StatusOK, gin.H{"user_id": userID, "status": "fetched"})
	})

	// Create and configure the MCP server
	mcp := server.New(r, &server.Config{
		Name:        "My Simple API",
		Description: "An example API automatically exposed via MCP.",
		BaseURL:     "http://localhost:8080",
	})

	// Mount the MCP server endpoint
	mcp.Mount("/mcp")

	// Run your Gin server
	r.Run(":8080")
}

After running this code, your MCP tools are available at http://localhost:8080/mcp. Gin-MCP automatically creates tools for all your defined routes.

Advanced Configuration

Custom Schema Registration

For more control over parameter and request body schemas:

package main

import (
	"github.com/ckanthony/gin-mcp/pkg/server"
	"github.com/gin-gonic/gin"
)

// Define schema structs
type ListProductsParams struct {
	Page  int    `form:"page,default=1" json:"page,omitempty" jsonschema:"description=Page number,minimum=1"`
	Limit int    `form:"limit,default=10" json:"limit,omitempty" jsonschema:"description=Items per page,maximum=100"`
	Tag   string `form:"tag" json:"tag,omitempty" jsonschema:"description=Filter by tag"`
}

type CreateProductRequest struct {
	Name  string  `json:"name" jsonschema:"required,description=Product name"`
	Price float64 `json:"price" jsonschema:"required,minimum=0,description=Product price"`
}

func main() {
	r := gin.Default()
	
	// Define your routes
	r.GET("/products", func(c *gin.Context) { /* handler */ })
	r.POST("/products", func(c *gin.Context) { /* handler */ })

	// Configure MCP server
	mcp := server.New(r, &server.Config{
		Name:        "Product API",
		Description: "API for managing products.",
		BaseURL:     "http://localhost:8080",
	})

	// Register custom schemas
	// For GET /products query parameters
	mcp.RegisterSchema("GET", "/products", ListProductsParams{}, nil)
	
	// For POST /products request body
	mcp.RegisterSchema("POST", "/products", nil, CreateProductRequest{})

	mcp.Mount("/mcp")
	r.Run(":8080")
}

Filtering Endpoints

Control which endpoints are exposed as MCP tools:

// Only expose specific operations by ID
mcp := server.New(r, &server.Config{
    Name:              "Filtered API",
    Description:       "API with filtered endpoints",
    BaseURL:           "http://localhost:8080",
    IncludeOperations: []string{"getUser", "listUsers"},
})

// Exclude specific operations
mcp := server.New(r, &server.Config{
    Name:              "Filtered API",
    Description:       "API with filtered endpoints",
    BaseURL:           "http://localhost:8080",
    ExcludeOperations: []string{"deleteUser"},
})

// Filter by tags
mcp := server.New(r, &server.Config{
    Name:        "Filtered API",
    Description: "API with filtered endpoints",
    BaseURL:     "http://localhost:8080",
    IncludeTags: []string{"public", "users"},
})

// Exclude by tags
mcp := server.New(r, &server.Config{
    Name:        "Filtered API",
    Description: "API with filtered endpoints",
    BaseURL:     "http://localhost:8080",
    ExcludeTags: []string{"admin", "internal"},
})

Connecting an MCP Client

Once your Gin-MCP server is running:

1. Start your application with the mounted MCP endpoint
2. In your MCP client (such as Cursor), go to Settings → MCP
3. Enter the URL of your MCP endpoint (e.g., http://localhost:8080/mcp)
4. The client will automatically discover and display your API tools

Important Notes

• Always specify a BaseURL in your configuration to ensure MCP clients can properly route requests
• You can only use one inclusion filter and one exclusion filter at a time
• When both inclusion and exclusion filters are used, exclusion takes precedence

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.