MCP OpenAPI Connector

A unified Model Context Protocol (MCP) server for connecting OpenAPI-based APIs with built-in authentication management. This project enables Claude Desktop, Cursor, and other MCP-compatible clients to interact with authenticated OpenAPI-based APIs without requiring separate proxy servers.

- Single Process Architecture: No separate proxy server needed
- Built-in OAuth2 Authentication: Automatic token management and refresh
- OpenAPI Integration: Automatically generate MCP tools from OpenAPI/Swagger specifications
- Extensible Tool System: Easy to add custom tools and resources
- Error Handling: Automatic retry and authentication error recovery
- Simple Configuration: Single configuration file for all settings
- Multiple API Support: Easily adapt to any OAuth2-based API

npm install -g @ssossan/mcp-openapi-connector

git clone https://github.com/ssossan/mcp-openapi-connector.git cd mcp-openapi-connector npm install

- Collect your API configuration through interactive prompts
- Generategenerated/.envfile with your settings
- Creategenerated/claude-desktop-config.jsonfor easy Claude Desktop integration
- Provide step-by-step instructions for Claude Desktop configuration

CLIENT_ID=your-client-id CLIENT_SECRET=your-client-secret API_BASE_URL=https://api.example.com AUTH_PATH=/oauth/token OPENAPI_SPEC_PATH=./config/openapi.json

For development with automatic recompilation:

{ "mcpServers": { "openapi-connector": { "command": "npx", "args": ["@ssossan/mcp-openapi-connector"], "env": { "CLIENT_ID": "your-client-id", "CLIENT_SECRET": "your-client-secret", "API_BASE_URL": "https://api.example.com", "AUTH_PATH": "/oauth/token", "OPENAPI_SPEC_PATH": "/path/to/openapi.json" } } } }

{ "mcpServers": { "openapi-connector": { "command": "mcp-openapi-connector", "env": { "CLIENT_ID": "your-client-id", "CLIENT_SECRET": "your-client-secret", "API_BASE_URL": "https://api.example.com", "AUTH_PATH": "/oauth/token", "OPENAPI_SPEC_PATH": "/path/to/openapi.json" } } } }

{ "mcpServers": { "openapi-connector": { "command": "node", "args": ["/path/to/mcp-openapi-connector/dist/mcp-openapi-connector.js"], "cwd": "/path/to/mcp-openapi-connector", "env": { "CLIENT_ID": "your-client-id", "CLIENT_SECRET": "your-client-secret", "API_BASE_URL": "https://api.example.com", "AUTH_PATH": "/oauth/token", "OPENAPI_SPEC_PATH": "/path/to/openapi.json" } } } }

The server automatically generates tools from an OpenAPI specification.An OpenAPI specification is required for the server to function.
- Place your OpenAPI spec file (JSON format) in the project
- Set the path in your environment:

OPENAPI_SPEC_PATH=./config/openapi.json OPENAPI_TOOL_PREFIX=api_ # Optional: prefix for generated tool names OPENAPI_INCLUDE_ONLY=listItems,createItem # Optional: only include specific operations OPENAPI_EXCLUDE=deleteItem # Optional: exclude specific operations

The server will automatically generate MCP tools from all operations in your OpenAPI spec. Without an OpenAPI specification, the server will only provide test/debug tools.

Create custom tools by adding a JavaScript file:

export default { register(server) { server.registerCustomTool('my_tool', { name: 'my_tool', description: 'My custom tool', inputSchema: { type: 'object', properties: { param: { type: 'string', required: true } } }, apiEndpoint: '/my-endpoint', method: 'POST' }); } };

Then setCUSTOM_TOOLS_PATHin your environment:

CUSTOM_TOOLS_PATH=./src/tools/my-custom-tools.ts

npm run build npm test npm publish --access public

npm run dev # Development mode with tsx npm run build # Compile TypeScript to JavaScript npm start # Build and run production version npm run test # Build and run test server npm run test:dev # Run test server in development mode npm run typecheck # Type check without compilation npm run clean # Remove build output

This project is built with TypeScript for better type safety and development experience:

- Source code:src/directory
- Build output:dist/directory
- Type definitions: Automatically generated.d.tsfiles

Claude Desktop ↔ MCP Server (stdio) → OpenAPI-based API ↓ TokenManager (OAuth2 handling)

- src/mcp-openapi-connector.ts- Main server entry point
- src/lib/token-manager.ts- OAuth2 token management with caching
- src/lib/saas-client.ts- HTTP client with automatic authentication
- src/lib/mcp-handler.ts- MCP protocol handling and tool registration
- src/lib/openapi-loader.ts- OpenAPI specification parser and tool generator
- src/types/- TypeScript type definitions

If you're using the previous gateway-based version:
- Remove the proxy server configuration
- Update your Claude Desktop config to point directly to this server
- Use the same environment variables (no changes needed)

Example: Using with a Generic OpenAPI-based API

See theconfig/openapi-example.jsonfile for a sample OpenAPI specification that demonstrates how to structure your API for MCP integration.

- Verify CLIENT_ID and CLIENT_SECRET are correct
- Check AUTH_URL points to the correct OAuth2 endpoint
- Ensure your credentials have the necessary scopes

- Check API_BASE_URL is correct
- Verify network connectivity
- Check server logs for detailed error messages

SetNODE_ENV=developmentfor verbose logging:

Contributions are welcome! Please feel free to submit a Pull Request.

Built using theModel Context Protocol SDKby Anthropic.

Converts OpenAPI specifications into MCP tools, enabling AI clients to interact with external APIs seamlessly.