spec2mcp

spec2mcp is a flexible API gateway built specifically for the Model Context Protocol (MCP). It dynamically transforms your REST APIs—defined via OpenAPI YAML/JSON specs—into native, executable MCP tools.

By bridging the gap between existing API infrastructures and AI agents, developers can expose powerful systems (e.g., GitHub, Stripe, Internal Microservices) to language models seamlessly without manual tool-wiring.

Overview

spec2mcp works by interpreting OpenAPI 3 schemas:

• Automatic Loading: Scans an apis/ directory for YAML/JSON specs and dynamically extracts endpoints into GET and POST tools.
• Dynamic FastMCP Server: Wraps endpoints in safe, asynchronous invocation boundaries using the FastMCP framework.
• Smart Authentication: Supports injecting Authorization headers, api_key query parameters, and extracting local environment variables across multiple specs simultaneously.

Installation

You can install spec2mcp via PyPI:

pip install spec2mcp

Quickstart

1. Create your specs directory: Create a folder called apis/ anywhere on your machine.

mkdir apis

2. Add an OpenAPI Specification: Save your API definitions inside apis/. For instance, you could place a subset of the GitHub REST API spec in apis/github.yaml.

3. Configure Authentication: If the APIs you are hitting require API keys, create an auth.json to store your authentication mappings. spec2mcp understands environment variable extraction out-of-the-box (${VARIABLE}).

{
  "github": {
    "headers": {
      "Authorization": "Bearer ${GITHUB_TOKEN}"
    }
  },
  "weather_api": {
    "query": {
      "api_key": "${WEATHER_API_KEY}"
    }
  }
}

4. Start the MCP Server! To run the server natively locally (or to provide the command string for an AI Agent's MCP config block):

python -m spec2mcp.cli serve ./apis --auth-config auth.json

Integrating into Claude Desktop / Cursor

Add the following to your MCP Configuration file mcp.json or mcp_config.json:

{
  "mcpServers": {
    "spec2mcp": {
      "command": "python",
      "args": [
        "-m", "spec2mcp.cli", 
        "serve", 
        "C:\\absolute\\path\\to\\apis", 
        "--auth-config", "C:\\absolute\\path\\to\\auth.json"
      ]
    }
  }
}

Restart your IDE or Desktop client, and your AI should natively understand and begin executing tools against the mapped API logic!

License

OpenMCP is licensed under the MIT License.