# OpenAPI MCP Server

A Model Context Protocol (MCP) server that dynamically exposes REST APIs as MCP tools by parsing OpenAPI specifications. Works with any OpenAPI-compliant API.

## Features

- **Dynamic Tool Generation**: Automatically creates MCP tools from OpenAPI specs
- **Two Operation Modes**: Low-level (automatic) and FastMCP (predefined)
- **Flexible Authentication**: Support for Bearer tokens, API keys, and custom headers
- **Endpoint Filtering**: Whitelist/blacklist specific API endpoints
- **Parameter Stripping**: Remove sensitive parameters from requests
- **Pre-built Presets**: Includes configurations for popular APIs

## Quick Start

```bash
# Install
pip install openapi-mcp-server

# Run with any OpenAPI service
openapi-mcp-server --openapi-url https://api.example.com/openapi.json --base-url https://api.example.com

# Use with Lemy (preset included)
openapi-mcp-server --preset lemy

# Test mode (verify tools without starting MCP)
openapi-mcp-server --preset lemy --test
```

## Presets

### Lemy
```bash
openapi-mcp-server --preset lemy
# or
OPENAPI_PRESET=lemy openapi-mcp-server
```

### Custom API
```bash
openapi-mcp-server \
  --openapi-url https://your-api.com/openapi.json \
  --base-url https://your-api.com \
  --mode fastmcp \
  --auth-token your-token
```

## Installation

### From PyPI

```bash
pip install openapi-mcp-server
```

Or with uv:
```bash
uv add openapi-mcp-server
```

### Local Installation (Development)

If you want to install from source for development or testing:

```bash
# Clone the repository
git clone https://github.com/yourusername/openapi-mcp-server.git
cd openapi-mcp-server

# Install in editable mode with development dependencies
pip install -e ".[dev]"

# Or with uv
uv pip install -e ".[dev]"

# Verify installation
openapi-mcp-server --help

# Run tests to ensure everything works
pytest
```

The editable installation (`-e` flag) allows you to modify the source code and see changes immediately without reinstalling.

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `OPENAPI_PRESET` | Preset name (lemy, slack, etc.) | None |
| `OPENAPI_SPEC_URL` | OpenAPI specification URL | Required |
| `API_BASE_URL` | API base URL | Required |
| `MCP_MODE` | Server mode (`low_level` or `fastmcp`) | `low_level` |
| `API_KEY` | API authentication key | None |
| `AUTH_HEADER` | Authentication header name | `Authorization` |
| `AUTH_TYPE` | Authentication type | `Bearer` |
| `TOOL_WHITELIST` | Comma-separated endpoint patterns | None |
| `TOOL_BLACKLIST` | Comma-separated endpoint patterns | None |
| `TOOL_NAME_PREFIX` | Prefix for tool names | `api_` |
| `STRIP_PARAM` | Parameter to remove from requests | None |
| `DEBUG` | Enable debug logging | `false` |

### Configuration File

Create a `config.json`:
```json
{
  "openapi_spec_url": "https://api.example.com/openapi.json",
  "api_base_url": "https://api.example.com",
  "mode": "fastmcp",
  "api_key": "your-token",
  "tool_whitelist": ["/users", "/posts"],
  "debug": true
}
```

Then run:
```bash
openapi-mcp-server --config config.json
```

## Usage with Claude Code

Add to your Claude Code MCP configuration:

```json
{
  "mcpServers": {
    "my-api": {
      "command": "openapi-mcp-server",
      "args": ["--preset", "lemy"],
      "env": {
        "API_BASE_URL": "http://localhost:11981"
      }
    }
  }
}
```

Or for a custom API:
```json
{
  "mcpServers": {
    "my-api": {
      "command": "openapi-mcp-server",
      "env": {
        "OPENAPI_SPEC_URL": "https://api.example.com/openapi.json",
        "API_BASE_URL": "https://api.example.com",
        "API_KEY": "your-token",
        "MCP_MODE": "fastmcp"
      }
    }
  }
}
```

## Presets

### Available Presets

- **lemy**: Lemy AI platform
- **slack**: Slack API (coming soon)
- **github**: GitHub API (coming soon)

### Creating Custom Presets

Create a preset file in `presets/my-service.json`:
```json
{
  "name": "my-service",
  "openapi_spec_url": "https://api.myservice.com/openapi.json",
  "api_base_url": "https://api.myservice.com",
  "mode": "fastmcp",
  "auth_header": "X-API-Key",
  "auth_type": "Token",
  "tool_name_prefix": "myservice_",
  "fastmcp_tools": [
    {
      "name": "myservice_get_user",
      "description": "Get user information",
      "endpoint": "/users/{id}",
      "method": "GET",
      "parameters": {
        "id": {"type": "string", "required": true, "in": "path"}
      }
    }
  ]
}
```

## Development

```bash
git clone https://github.com/yourusername/openapi-mcp-server
cd openapi-mcp-server
pip install -e ".[dev]"

# Run tests
pytest

# Test with Lemy
openapi-mcp-server --preset lemy --test
```

## Examples

### Slack API
```bash
openapi-mcp-server \
  --openapi-url https://api.slack.com/specs/openapi/v2/slack_web.json \
  --base-url https://slack.com/api \
  --auth-token xoxb-your-token \
  --tool-prefix slack_
```

### GitHub API
```bash
openapi-mcp-server \
  --openapi-url https://api.github.com/openapi.json \
  --base-url https://api.github.com \
  --auth-token ghp_your-token \
  --auth-header Authorization \
  --auth-type "Bearer"
```

### Custom Internal API
```bash
openapi-mcp-server \
  --openapi-url http://internal-api:8080/openapi.json \
  --base-url http://internal-api:8080 \
  --mode fastmcp \
  --whitelist "/api/v1/users,/api/v1/projects"
```

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for your changes
4. Ensure all tests pass
5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.