spaceguy101/openapi-to-mcpserver
If you are the rightful owner of openapi-to-mcpserver and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.
OpenAPI to MCP converts an OpenAPI specification file into an MCP server for interacting with web APIs.
OpenAPI to MCP
Converts an OpenAPI specification file into an MCP server that can be used to interact with existing web APIs described by OpenAPI specifications.
This allows AI agents or other clients that understand MCP to interact with existing web APIs described by OpenAPI specifications.
Features
- Automatic conversion of OpenAPI operations to MCP tools
- Support for both modern Streamable HTTP and legacy SSE transports
- Automatic API base URL detection from OpenAPI specs
- Support for OpenAPI/Swagger 2.0 and OpenAPI 3.x
- Binary response handling
- Graceful shutdown handling
- Detailed logging for debugging
Prerequisites
- Node.js (v16 or later recommended)
Installation
- Clone the repository (or ensure you have the
openapi-to-mcpdirectory). - Navigate to the
openapi-to-mcpdirectory:cd openapi-to-mcp - Install dependencies:
npm install
Build
Compile the TypeScript code to JavaScript:
npm run build
This will create a dist directory with the compiled JavaScript files.
Usage
Start the server using the start script, providing the path to your OpenAPI specification file using the -f or --file option:
# Example using a local petstore.yaml file
npm start -- serve -f ./path/to/your/openapi.json
# Example with different port and host
npm start -- serve --file ./specs/petstore.json --port 9090 --host 0.0.0.0
- Replace
./path/to/your/openapi.jsonwith the actual path to your OpenAPI file. - The server will parse the file, adapt the API operations to MCP functions, and start listening.
- It will print the available endpoints for both modern and legacy MCP connections.
Connecting as an MCP Client
Modern Connection (Recommended)
The server provides a modern Streamable HTTP transport managed by the MCP SDK. This is the recommended way to connect to the server.
Legacy SSE Connection
For backwards compatibility, the server also supports SSE connections:
-
Connect to the SSE endpoint (e.g.,
http://localhost:8080/sse). -
You will receive an
mcp-helloevent upon connection. -
To call a function, send an MCP
function_callmessage via a POST request to the/messagesendpoint with asessionIdquery parameter matching your SSE connection ID.Example POST to
/messages?sessionId=<your_session_id>:Headers:
Content-Type: application/jsonBody:
{ "type": "function_call", "id": "call-123", "function_name": "get_pets_by_status", "parameters": { "status": "available" } } -
The server will execute the corresponding API call and send back a
function_returnorerrorevent over the established SSE connection.
Development
Run in development mode with auto-recompilation:
# Make sure to provide the OpenAPI file path
npm run dev -- -f ./path/to/your/openapi.yaml
Current Limitations
- Authentication: Not implemented
- Schema Validation: While basic schema validation is in place, some complex OpenAPI schema features (discriminators, complex compositions) might not be fully supported.
- Testing: No automated tests are currently included.
- Documentation: Individual tool documentation could be improved with more examples and parameter descriptions.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
