openapi-mcp - Transform OpenAPI Specs into MCP Tool Servers

Key Features

🚀

Instant API to MCP Conversion

Parse any OpenAPI 3.x YAML/JSON spec and generate MCP tools automatically. Get up and running in seconds.

🤖

AI-Optimized

Unique features designed specifically for AI agents with structured responses, rich schema information, intelligent error handling, and machine-optimized output formats.

🔒

Comprehensive Authentication

API key, Bearer token, Basic auth, and OAuth2 support for all your authentication needs.

🛡️

Safety Features

Built-in confirmation workflow for dangerous operations (PUT/POST/DELETE) to prevent accidental changes.

📚

Library Integration

Import as a Go module in your projects for seamless integration with your own applications.

🔍

Validation & Linting

Powerful OpenAPI validation and linting with actionable suggestions. Validate for critical issues or lint for comprehensive best practices analysis.

Quick Start

1. Build from Source

# Clone the repository
git clone https://github.com/jedisct1/openapi-mcp.git
cd openapi-mcp

# Build the binaries
make

# This will create:
# - bin/openapi-mcp (main tool)
# - bin/mcp-client (interactive client)

2. Validate & Lint (Optional)

# Validate your OpenAPI spec for critical issues
bin/openapi-mcp validate examples/fastly-openapi-mcp.yaml

# Comprehensive linting with best practice suggestions
bin/openapi-mcp lint examples/fastly-openapi-mcp.yaml

3. Run the MCP Server

# Basic usage (stdio mode)
bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# With API key
API_KEY=your_api_key bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# As HTTP server
bin/openapi-mcp --http=:8080 examples/fastly-openapi-mcp.yaml

4. Use the Interactive Client

# Start the client (connects to openapi-mcp via stdio)
bin/mcp-client bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# Client commands
mcp> list                              # List available tools
mcp> schema <tool-name>                # Show tool schema
mcp> call <tool-name> {arg1: value1}   # Call a tool with arguments
mcp> describe                          # Get full API documentation

5. Filter Operations (New!)

# Output only admin-tagged operations as JSON
bin/openapi-mcp filter --tag=admin examples/fastly-openapi-mcp.yaml

# Output operations whose description matches 'foo'
bin/openapi-mcp filter --include-desc-regex=foo examples/fastly-openapi-mcp.yaml

# Combine filters
bin/openapi-mcp filter --tag=admin --include-desc-regex=foo examples/fastly-openapi-mcp.yaml

This will output a JSON array of operations matching the filters, including their name, description, tags, and input schema.

AI Agent Integration

openapi-mcp features unique AI optimizations that set it apart from standard API-to-tool converters:

Structured JSON Responses: Every response includes OutputFormat and OutputType fields for consistent parsing
Rich Schema Information: All tools provide detailed parameter constraints and examples that help AI agents understand API requirements
Actionable Error Messages: Validation errors include detailed information and suggestions that guide agents toward correct usage
Safety Confirmations: Standardized confirmation workflow for dangerous operations prevents unintended consequences
Self-Describing API: The describe tool provides complete, machine-readable documentation for all operations
Minimal Verbosity: No redundant warnings or messages to confuse agents—outputs are optimized for machine consumption
Smart Parameter Handling: Automatic conversion between OpenAPI parameter types and MCP tool parameters
Contextual Examples: Every tool includes context-aware examples based on the OpenAPI specification

Integration with AI Code Editors

You can easily integrate openapi-mcp with AI code editors that support MCP tools, such as Roo Code:

{
    "fastly": {
        "command": "/opt/bin/openapi-mcp",
        "args": [
            "-api-key",
            "YOUR_API_KEY",
            "/opt/etc/openapi/fastly-openapi-mcp.yaml"
        ]
    }
}

Simply add this configuration to your editor's MCP tools configuration to provide AI assistants with direct access to the API.

Example Output Structure

{
  "OutputFormat": "structured",
  "OutputType": "json",
  "type": "api_response",
  "data": {
    // API-specific response data
  },
  "metadata": {
    "status_code": 200,
    "headers": {
      // Response headers
    }
  }
}

Library Usage

openapi-mcp can be imported as a Go module in your projects, enabling you to integrate MCP server capabilities directly into your applications.

Installation

# Main library for OpenAPI to MCP conversion
go get github.com/jedisct1/openapi-mcp/pkg/openapi2mcp

# MCP server package for server functionality
go get github.com/jedisct1/openapi-mcp/pkg/mcp/server

# MCP types package for core MCP utilities
go get github.com/jedisct1/openapi-mcp/pkg/mcp/mcp

Basic Usage

package main

import (
	"log"
	"github.com/jedisct1/openapi-mcp/pkg/openapi2mcp"
)

func main() {
	// Load OpenAPI spec
	doc, err := openapi2mcp.LoadOpenAPISpec("openapi.yaml")
	if err != nil {
		log.Fatal(err)
	}
	
	// Create MCP server
	srv := openapi2mcp.NewServer("myapi", doc.Info.Version, doc)
	
	// Serve over HTTP
	if err := openapi2mcp.ServeStreamableHTTP(srv, ":8080", "/mcp"); err != nil {
		log.Fatal(err)
	}
}

Advanced Usage with MCP Package

import (
	"context"
	"github.com/jedisct1/openapi-mcp/pkg/mcp/mcp"
	"github.com/jedisct1/openapi-mcp/pkg/mcp/server"
	"github.com/jedisct1/openapi-mcp/pkg/openapi2mcp"
)

// Create server and add custom tools
srv := server.NewMCPServer("myapi", "1.0")
ops := openapi2mcp.ExtractOpenAPIOperations(doc)
openapi2mcp.RegisterOpenAPITools(srv, ops, doc, nil)

// Add custom tools using MCP package directly
customTool := mcp.NewTool("custom", 
	mcp.WithDescription("A custom tool"),
	mcp.WithString("message", mcp.Required()))

srv.AddTool(customTool, handlerFunc)

See our comprehensive documentation:

Transform OpenAPI Specs into AI-Friendly Tools