OpenAPI to MCP Converter Convert any OpenAPI specification into a Model Context Protocol (MCP) server that AI assistants can use to interact with REST APIs. ## Features - Universal OpenAPI Support: Works with OpenAPI v3.0 and v3.1 specifications - Flexible Input: Accept OpenAPI specs from URLs or raw JSON/YAML strings - Smart Filtering: Include/exclude endpoints using regex patterns - Authentication Support: Bearer tokens, API keys, and basic auth - Multiple Output Formats: Generate MCP server packages, JSON manifests, or both - Production Ready: Includes error handling, validation, and structured logging ## How It Works 1. Input: Provide an OpenAPI specification URL or raw spec 2. Parse: Extract endpoints, parameters, request/response schemas 3. Transform: Convert each endpoint into an MCP tool with proper schemas 4. Generate: Create a ready-to-use MCP server package or JSON manifest 5. Deploy: Use the generated MCP server with any AI assistant ## Input Parameters ### Required - openapiSource (string): URL or raw JSON/YAML of the OpenAPI specification ### Optional - serverName (string): Unique identifier for the MCP server (default: openapi-mcp-server) - serverDescription (string): Human-readable description - includeEndpoints (array): Regex patterns to include specific endpoints - excludeEndpoints (array): Regex patterns to exclude endpoints - authentication (object): Auth configuration - type: none, bearer, apiKey, or basic - token: Bearer token or API key value - apiKeyHeader: Header name for API key (e.g., X-API-Key) - username: For basic auth - password: For basic auth - baseUrl (string): Override the base URL from the spec - outputFormat (string): mcp-package, json-manifest, or both (default: both) - includeExamples (boolean): Include examples in tool descriptions (default: true) - maxEndpoints (integer): Maximum endpoints to process (default: 100, max: 500) ## Output ### Dataset Each run produces a dataset with: 1. Summary record: Overview of processed endpoints 2. Endpoint records: Detailed info for each API endpoint including MCP tool name ### Key-Value Store - manifest.json: Complete MCP manifest with all tools and metadata - mcp-server.zip: Ready-to-deploy MCP server package (includes package.json, index.js, README.md) ## Usage Examples ### Basic Usage json { "openapiSource": "https://petstore3.swagger.io/api/v3/openapi.json", "serverName": "petstore-mcp", "serverDescription": "MCP server for Petstore API" } ### With Authentication json { "openapiSource": "https://api.example.com/openapi.json", "serverName": "example-api-mcp", "authentication": { "type": "bearer", "token": "your-api-token-here" } } ### With Endpoint Filtering json { "openapiSource": "https://api.example.com/openapi.json", "includeEndpoints": ["GET /users.*", "POST /users"], "excludeEndpoints": ["DELETE .*"] } ### From Raw YAML json { "openapiSource": "openapi: 3.0.0\ninfo:\n title: My API\n version: 1.0.0\npaths:\n /hello:\n get:\n summary: Say hello\n responses:\n '200':\n description: Success" } ## Deploying the MCP Server After the actor completes: 1. Download mcp-server.zip from the key-value store 2. Extract the archive 3. Install dependencies: npm install 4. Run the server: node index.js 5. Connect it to your AI assistant (Claude Desktop, etc.) ### Example MCP Configuration (Claude Desktop) json { "mcpServers": { "petstore-mcp": { "command": "node", "args": ["/path/to/extracted/mcp-server/index.js"] } } } ## API Integration Use the Apify API to automate OpenAPI to MCP conversion: javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_API_TOKEN' }); const run = await client.actor('YOUR_USERNAME/openapi-to-mcp-converter').call({ openapiSource: 'https://api.example.com/openapi.json', serverName: 'my-api-mcp', authentication: { type: 'bearer', token: process.env.API_TOKEN, }, }); const { defaultKeyValueStoreId } = run; const kvStore = client.keyValueStore(defaultKeyValueStoreId); // Download the MCP server package const mcpPackage = await kvStore.getValue('mcp-server.zip'); ## Use Cases - API Integration: Make any REST API accessible to AI assistants - Legacy API Modernization: Bridge old APIs with modern AI tooling - Rapid Prototyping: Quickly test AI interactions with APIs - Multi-API Orchestration: Create multiple MCP servers for different services - Developer Tools: Generate MCP servers for internal APIs ## Limitations - Only supports OpenAPI v3.0 and v3.1 - Complex authentication flows (OAuth2, etc.) require manual customization - Generated MCP server code is a starting point and may need refinement for production - Maximum 500 endpoints per run ## Technical Details - Runtime: Node.js 18+ - Dependencies: apify, openapi-types, yaml, zod, archiver, fs-extra - Output: MCP SDK v1.0+ compatible servers ## Troubleshooting ### "Failed to fetch OpenAPI spec" - Verify the URL is accessible - Check if authentication is required for the spec endpoint - Ensure the URL returns valid JSON or YAML ### "No endpoints found" - Check your include/exclude patterns - Verify the OpenAPI spec has valid paths - Increase maxEndpoints if needed ### "Invalid OpenAPI specification" - Ensure the spec is valid OpenAPI v3.0 or v3.1 - Use an OpenAPI validator to check the spec first - Try converting v2.0 (Swagger) specs to v3.0 first ## Support For issues, feature requests, or questions, please open an issue on the actor's repository.