mcp-server-openapi by mandar-p - MCP Server

MCP OpenAPI Server

Author: Mandar Paithankar
Version: 1.0.0

A Model Context Protocol (MCP) server that dynamically creates tools from OpenAPI 3.0 specifications. This server automatically generates callable tools for each API endpoint defined in your OpenAPI spec, enabling Claude AI to interact with any REST API seamlessly.

🚀 Features

Dynamic Tool Generation: Automatically creates MCP tools from OpenAPI 3.0 JSON specifications
Complete OpenAPI Support: Full support for OpenAPI 3.0 and 3.1 specifications
Smart Parameter Handling: Supports path, query, header, and body parameters with validation
Authentication Ready: Configurable authorization headers (Bearer tokens, API keys, custom headers)
Beautiful Responses: Pretty-prints JSON responses with proper error handling
HTTP Method Support: GET, POST, PUT, DELETE, PATCH, HEAD, and OPTIONS
Zero Configuration: Just point to your OpenAPI spec and go!

🛠️ Built With

Go 1.21+: High-performance systems programming language
Model Context Protocol Go SDK: Official MCP implementation by Anthropic
Go Standard Library: Native HTTP client, JSON parsing, and networking

📦 Installation

Prerequisites

Go 1.21 or higher
An OpenAPI 3.0 specification file (JSON format)

Quick Start

Clone the repository:

git clone https://github.com/mandarpaithankar/mcp-openapi-server.git
cd mcp-openapi-server

Install dependencies:
```
go mod tidy
```
Build the server:
```
chmod +x build.sh
./build.sh
```

Run with sample API:

./mcp-openapi-server -spec sample-petstore.json

🎯 Usage

Basic Usage

# Run with your OpenAPI spec
./mcp-openapi-server -spec your-api-spec.json

# With authentication
./mcp-openapi-server -spec your-api-spec.json -auth "Bearer your-token"

# With custom base URL
./mcp-openapi-server -spec your-api-spec.json -base-url https://api.example.com

# Custom host and port
./mcp-openapi-server -spec your-api-spec.json -host 0.0.0.0 -port 9000

Command Line Options

Option	Description	Example
`-spec`	Path to OpenAPI 3.0 JSON file (required)	`-spec ./api.json`
`-base-url`	Override base URL for API calls	`-base-url https://api.example.com`
`-auth`	Authorization header value	`-auth "Bearer token123"`
`-host`	Host to listen on (default: localhost)	`-host 0.0.0.0`
`-port`	Port to listen on (default: 8080)	`-port 9000`

🔗 Integration with Claude Desktop

Method 1: Direct Binary (Recommended)

Add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "openapi-server": {
      "command": "/path/to/mcp-openapi-server/mcp-openapi-server",
      "args": [
        "-spec", "/path/to/your/openapi-spec.json",
        "-auth", "Bearer your-token"
      ]
    }
  }
}

Method 2: Using mcp-remote

Start the server:

./mcp-openapi-server -spec your-api-spec.json

Add to Claude Desktop config:

{
  "mcpServers": {
    "openapi-server": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8080/openapi"]
    }
  }
}

Configuration File Location

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

📋 OpenAPI Requirements

Format: JSON only (YAML not supported)
Version: OpenAPI 3.0 or 3.1
Required Fields:
- openapi: Version number
- info: API information
- paths: API endpoints
- servers: At least one server URL (unless overridden with -base-url)

Example OpenAPI Structure

{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "servers": [
    {"url": "https://api.example.com/v1"}
  ],
  "paths": {
    "/users/{id}": {
      "get": {
        "summary": "Get user by ID",
        "operationId": "getUserById",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {"type": "integer"}
          }
        ]
      }
    }
  }
}

⚡ How It Works

Spec Loading: Reads and validates your OpenAPI 3.0 JSON specification
Tool Registration: Creates an MCP tool for each API endpoint/method combination
Request Handling: When Claude calls a tool:
- Validates required parameters
- Builds the complete request URL
- Adds proper headers and authentication
- Makes the HTTP request
- Returns formatted results

🔧 Tool Naming

Tools are automatically named based on your API endpoints:

With operationId: api_{operationId} → api_getUserById
Without operationId: api_{method}_{path} → api_get_users_id

🧪 Testing

Validate Your OpenAPI Spec

go run test-spec.go your-openapi-spec.json

Test with Sample API

# Use the included Petstore API sample
./mcp-openapi-server -spec sample-petstore.json

# In Claude, try asking:
# "Get pet with ID 1"
# "Find pets with status available"
# "What API endpoints are available?"

Example Claude Interactions

Once connected to Claude, you can make requests like:

"Get user details for user ID 123"
"Create a new pet with name 'Buddy' and status 'available'"
"List all orders with status 'pending'"
"What API tools are available to me?"

🛡️ Security Features

Parameter Validation: Validates required parameters before API calls
Input Sanitization: Properly escapes URL parameters and headers
Timeout Protection: 30-second timeout on all HTTP requests
Error Handling: Detailed error messages without exposing sensitive data

🚀 Performance

Fast Startup: Loads and validates OpenAPI specs in milliseconds
Efficient Memory Usage: Minimal memory footprint
Concurrent Requests: Handles multiple API calls simultaneously
HTTP/2 Support: Uses Go's modern HTTP client with connection pooling

📝 Examples

E-commerce API Integration

./mcp-openapi-server -spec shopify-api.json -auth "X-Shopify-Access-Token your-token"

GitHub API Integration

./mcp-openapi-server -spec github-api.json -auth "Bearer ghp_your-token"

Custom Internal API

./mcp-openapi-server -spec internal-api.json -base-url https://internal.company.com -auth "Bearer jwt-token"

🎬 Getting Started Video

Want to see it in action? Check out our getting started guide:

Download any OpenAPI 3.0 spec (try Swagger Petstore)
Save it as JSON format
Run: ./mcp-openapi-server -spec your-spec.json
Connect to Claude Desktop
Start making API calls through natural language!

🤝 Contributing

We welcome contributions! Please see for guidelines.

Quick Development Setup

git clone https://github.com/mandarpaithankar/mcp-openapi-server.git
cd mcp-openapi-server
go mod tidy
./build.sh

📚 Documentation

: List of all open source libraries used
: How to contribute to this project
: Usage examples and demos

🐛 Troubleshooting

Common Issues

Build fails: Ensure Go 1.21+ is installed and go mod tidy was run
Connection refused: Check if the port is available and firewall settings
Invalid spec: Validate your OpenAPI spec with the test tool
Authentication errors: Verify your auth header format and API key validity

Getting Help

Check existing Issues
Run the examples script: ./examples.sh
Validate your spec: go run test-spec.go your-spec.json
Open a new issue with details about your setup

🏗️ Roadmap

🙏 Acknowledgments

Anthropic for creating the Model Context Protocol
OpenAPI Initiative for the OpenAPI Specification
Go Community for excellent tooling and libraries

📊 Stats

Language: Go
Dependencies: Minimal (just MCP SDK + standard library)
Size: < 5MB binary
Performance: Handles 1000+ requests/second
Memory: < 50MB typical usage

Made with ❤️ by Mandar Paithankar

Transform any REST API into Claude-compatible tools in seconds!