Ivo Toby MCP Openapi Server

🚀 OpenAPI MCP Server

An MCP server that provides MCP resources through OpenAPI endpoints. This server allows large language models to discover and interact with REST APIs defined by OpenAPI specifications via the MCP protocol.

🚀 Quick Start

You don't need to clone this repository to use this MCP server. You just need to configure it in Claude Desktop:

1. Locate or create your Claude Desktop configuration file:

   • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the following configuration to enable the OpenAPI MCP server:

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json",
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key"
      }
    }
  }
}

3. Replace the environment variables with your actual API configuration:
   • API_BASE_URL: The base URL of the API
   • OPENAPI_SPEC_PATH: The path or URL to the OpenAPI specification
   • API_HEADERS: Key-value pairs for API authentication, separated by commas

🛠️ Development Tools

This project includes several development tools to make your workflow easier:

Build

• npm run build - Compile TypeScript source code
• npm run clean - Remove build artifacts
• npm run typecheck - Run TypeScript type checking

Development Mode

• npm run dev - Watch source files and rebuild on changes
• npm run inspect-watch - Run the inspector and automatically reload changes

Code Quality

• npm run lint - Run ESLint
• npm run typecheck - Validate TypeScript types

⚙️ Configuration

The server can be configured via environment variables or command-line arguments:

Environment Variables

• API_BASE_URL - The base URL of the API endpoints
• OPENAPI_SPEC_PATH - The path or URL to the OpenAPI specification
• API_HEADERS - Key-value pairs for API headers, separated by commas
• SERVER_NAME - The name of the MCP server (Default: "mcp-openapi-server")
• SERVER_VERSION - The server version (Default: "1.0.0")

Command-Line Arguments

npm run inspect -- \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  --name "my-mcp-server" \
  --version "1.0.0"

🔨 Development Workflow

1. Start the development environment:

npm run inspect-watch

2. Make changes to the TypeScript files in src/
3. The server will automatically rebuild and restart
4. Test your changes using the MCP inspector UI

🐞 Debugging

The server outputs debug logs to the standard error stream. To view these logs:

1. In development mode:

   • The logs are displayed in the terminal where inspect-watch is running

2. When running directly:

npm run inspect 2>debug.log

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes
4. Run tests and code checks:

   npm run typecheck
   npm run lint
   

5. Submit a pull request