mcp-openapi-connector

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.

Features

• 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

Installation

Via npm (Recommended)

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

Or use directly with npx:

npx @ssossan/mcp-openapi-connector

From Source

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

Quick Setup (Recommended)

Run the interactive setup wizard:

npm run setup

This will:

• Collect your API configuration through interactive prompts
• Generate generated/.env file with your settings
• Create generated/claude-desktop-config.json for easy Claude Desktop integration
• Provide step-by-step instructions for Claude Desktop configuration

Manual Configuration

Alternatively, you can set up manually:

1. Copy .env.example to .env:

cp .env.example .env

2. Edit .env with your API credentials:

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

Usage

Development Mode

For development with automatic recompilation:

npm run dev

Production Mode

Build and run the compiled version:

npm run build
npm start

Claude Desktop Configuration

Add to your Claude Desktop config file:

Using npm package (Recommended):

{
  "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"
      }
    }
  }
}

Using global installation:

{
  "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"
      }
    }
  }
}

Using from source:

{
  "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"
      }
    }
  }
}

OpenAPI Integration

The server automatically generates tools from an OpenAPI specification. An OpenAPI specification is required for the server to function.

1. Place your OpenAPI spec file (JSON format) in the project
2. 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.

Custom 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 set CUSTOM_TOOLS_PATH in your environment:

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

Publishing to npm

For maintainers:

npm run build
npm test
npm publish --access public

Development

Available Scripts

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

TypeScript Development

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.ts files

Architecture

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

Key Components

• 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

Migration from v1.x

If you're using the previous gateway-based version:

1. Remove the proxy server configuration
2. Update your Claude Desktop config to point directly to this server
3. Use the same environment variables (no changes needed)

Example: Using with a Generic OpenAPI-based API

See the config/openapi-example.json file for a sample OpenAPI specification that demonstrates how to structure your API for MCP integration.

Troubleshooting

Authentication Errors

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

Connection Issues

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

Debug Mode

Set NODE_ENV=development for verbose logging:

NODE_ENV=development npm run dev

Contributing

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

License

MIT

Acknowledgments

Built using the Model Context Protocol SDK by Anthropic.