# 🚂 Railway OpenWebUI MCP Tool

A comprehensive Model Context Protocol (MCP) tool for deploying, managing, and monitoring OpenWebUI instances on the Railway platform.

![Railway](https://img.shields.io/badge/Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white)
![OpenWebUI](https://img.shields.io/badge/OpenWebUI-412991?style=for-the-badge&logo=openai&logoColor=white)
![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-Compatible-green?style=for-the-badge)

## 📋 Table of Contents

- [Overview](#-overview)
- [Features](#-features)
- [Prerequisites](#-prerequisites)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Usage](#-usage)
- [API Reference](#-api-reference)
- [MCP Tools Reference](#-mcp-tools-reference)
- [Deployment Templates](#-deployment-templates)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [License](#-license)

## 🌟 Overview

This MCP tool provides a seamless interface for deploying and managing OpenWebUI on Railway's cloud platform. It enables AI assistants and automation systems to:

- Deploy new OpenWebUI instances with a single command
- Manage existing deployments (scale, restart, update)
- Monitor resource usage and logs
- Configure environment variables and domains
- Handle database provisioning (PostgreSQL/Redis)

### What is OpenWebUI?

[OpenWebUI](https://github.com/open-webui/open-webui) is a self-hosted web interface for running and interacting with Large Language Models (LLMs). It supports multiple backends including Ollama and OpenAI-compatible APIs.

### What is Railway?

[Railway](https://railway.app) is a modern cloud platform that makes it easy to deploy, manage, and scale applications. It offers automatic SSL, custom domains, and seamless database provisioning.

### What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a standard for connecting AI assistants to external tools and data sources. This tool implements MCP to allow AI assistants like Claude to deploy and manage OpenWebUI instances.

## ✨ Features

### Core Deployment
- 🚀 **One-Click Deploy**: Deploy OpenWebUI with sensible defaults
- 🔧 **Custom Configuration**: Full control over environment variables
- 🗄️ **Database Integration**: Automatic PostgreSQL/Redis provisioning
- 🌐 **Custom Domains**: Easy domain configuration and SSL
- 📦 **Volume Persistence**: Persistent storage for data

### Management
- 📊 **Resource Monitoring**: CPU, memory, and bandwidth metrics
- 📝 **Log Streaming**: Real-time deployment logs
- 🔄 **Rolling Updates**: Zero-downtime deployments
- ⚡ **Auto-Scaling**: Configure scaling policies
- 🔁 **Version Management**: Easy version updates

### Integration
- 🤖 **MCP Compatible**: Works with Claude and other MCP clients
- 🔗 **Webhook Support**: Integration with CI/CD pipelines
- 🔐 **Secure**: API key management and secrets handling
- 🐳 **Docker Ready**: Full containerization support

## 📦 Prerequisites

- Python 3.10+
- Railway Account with API Token
- MCP-compatible client (e.g., Claude Desktop, or use as library)

## 🛠️ Installation

### Option 1: pip install (Recommended)

```bash
pip install railway-openwebui-mcp
```

### Option 2: From source

```bash
git clone https://github.com/chad-atexpedient/Railway-OpenwebUI-Tool.git
cd Railway-OpenwebUI-Tool
pip install -e .
```

### Option 3: Docker

```bash
docker build -t railway-openwebui-mcp .
docker run -e RAILWAY_API_TOKEN=your_token railway-openwebui-mcp
```

### Option 4: Using uvx (no installation)

```bash
uvx railway-openwebui-mcp
```

## ⚙️ Configuration

### 1. Get Railway API Token

1. Go to [Railway Dashboard](https://railway.app/account/tokens)
2. Click "Create Token"
3. Give it a descriptive name (e.g., "MCP Tool")
4. Copy the generated token

### 2. Environment Variables

Create a `.env` file in your project directory:

```env
# Required
RAILWAY_API_TOKEN=your_railway_api_token

# Optional
DEFAULT_REGION=us-west1
LOG_LEVEL=INFO
MCP_SERVER_PORT=8080
```

### 3. MCP Client Configuration

#### For Claude Desktop

Add to your `claude_desktop_config.json`:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "railway-openwebui": {
      "command": "python",
      "args": ["-m", "railway_openwebui_mcp"],
      "env": {
        "RAILWAY_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

#### Using uvx (recommended for Claude Desktop)

```json
{
  "mcpServers": {
    "railway-openwebui": {
      "command": "uvx",
      "args": ["railway-openwebui-mcp"],
      "env": {
        "RAILWAY_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

## 🚀 Usage

### Quick Start (Python Library)

```python
from railway_openwebui_mcp import RailwayOpenWebUI

# Initialize the client
client = RailwayOpenWebUI(api_token="your_token")

# Deploy OpenWebUI
deployment = client.deploy_openwebui(
    project_name="my-openwebui",
    region="us-west1",
    enable_signup=True,
    database_type="postgresql",
    redis_enabled=True
)

print(f"🚀 Deployed at: {deployment.url}")
print(f"📋 Project ID: {deployment.project_id}")
print(f"🔧 Service ID: {deployment.service_id}")
```

### MCP Tool Commands (Natural Language)

Once configured with an MCP client, you can use natural language:

| Command | Description |
|---------|-------------|
| "Deploy a new OpenWebUI instance called 'my-ai-chat'" | Creates new deployment |
| "Show me the status of my OpenWebUI deployment" | Gets deployment status |
| "Show me the logs for my OpenWebUI" | Retrieves recent logs |
| "Scale my OpenWebUI to 2 replicas" | Adjusts scaling |
| "Add custom domain chat.example.com to my deployment" | Configures domain |
| "Update my OpenWebUI to the latest version" | Triggers update |
| "What's the resource usage of my OpenWebUI?" | Gets metrics |
| "List all my Railway projects" | Lists projects |
| "Delete my OpenWebUI deployment" | Removes deployment |

### Advanced Usage

#### Deploy with OAuth

```python
deployment = client.deploy_openwebui(
    project_name="secure-openwebui",
    enable_signup=False,
    enable_oauth=True,
    oauth_providers=[
        {
            "provider": "google",
            "client_id": "your-google-client-id",
            "client_secret": "your-google-client-secret"
        },
        {
            "provider": "github",
            "client_id": "your-github-client-id",
            "client_secret": "your-github-client-secret"
        }
    ]
)
```

#### Deploy with Custom Environment

```python
deployment = client.deploy_openwebui(
    project_name="custom-openwebui",
    custom_env={
        "OLLAMA_BASE_URL": "https://your-ollama-instance.com",
        "OPENAI_API_KEY": "sk-your-openai-key",
        "WEBUI_NAME": "My Custom AI Chat",
        "DEFAULT_MODELS": "gpt-4,gpt-3.5-turbo",
        "ENABLE_RAG_WEB_SEARCH": "true"
    }
)
```

#### Monitor and Manage

```python
# Get status
status = client.get_deployment_status(project_id="your-project-id")
print(f"Status: {status.status}")
print(f"Health: {status.health}")
print(f"Uptime: {status.uptime}")

# Get logs
logs = client.get_logs(
    project_id="your-project-id",
    service_id="your-service-id",
    lines=50
)
for log in logs:
    print(log)

# Scale deployment
result = client.scale_deployment(
    project_id="your-project-id",
    service_id="your-service-id",
    replicas=2,
    memory_limit_mb=1024
)

# Update deployment
client.update_deployment(
    project_id="your-project-id",
    service_id="your-service-id",
    new_version="latest",
    env_updates={"WEBUI_NAME": "Updated Name"}
)
```

## 📚 API Reference

### Core Functions

#### `deploy_openwebui()`

Deploy a new OpenWebUI instance.

```python
def deploy_openwebui(
    project_name: str,
    region: str = "us-west1",
    environment: str = "production",
    openwebui_version: str = "latest",
    enable_signup: bool = True,
    enable_oauth: bool = False,
    oauth_providers: list = None,
    database_type: str = "postgresql",
    redis_enabled: bool = True,
    custom_env: dict = None,
    volume_size_gb: int = 10
) -> Deployment
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `project_name` | str | required | Name for the Railway project |
| `region` | str | "us-west1" | Deployment region (us-west1, us-east4, europe-west4) |
| `environment` | str | "production" | Environment name |
| `openwebui_version` | str | "main" | OpenWebUI Docker tag |
| `enable_signup` | bool | True | Allow new user registration |
| `enable_oauth` | bool | False | Enable OAuth authentication |
| `oauth_providers` | list | None | List of OAuth provider configs |
| `database_type` | str | "postgresql" | Database type (postgresql, sqlite) |
| `redis_enabled` | bool | True | Enable Redis for caching |
| `custom_env` | dict | None | Additional environment variables |
| `volume_size_gb` | int | 10 | Persistent volume size |

**Returns:** `Deployment` object

---

#### `get_deployment_status()`

Get the current status of a deployment.

```python
def get_deployment_status(
    project_id: str,
    service_id: str = None
) -> DeploymentStatus
```

---

#### `update_deployment()`

Update an existing deployment.

```python
def update_deployment(
    project_id: str,
    service_id: str,
    env_updates: dict = None,
    new_version: str = None,
    restart: bool = False
) -> Deployment
```

---

#### `scale_deployment()`

Scale deployment resources.

```python
def scale_deployment(
    project_id: str,
    service_id: str,
    replicas: int = None,
    cpu_limit: float = None,
    memory_limit_mb: int = None
) -> ScaleResult
```

---

#### `get_logs()`

Retrieve deployment logs.

```python
def get_logs(
    project_id: str,
    service_id: str,
    lines: int = 100,
    follow: bool = False,
    since: datetime = None
) -> List[str]
```

---

#### `configure_domain()`

Add or configure a custom domain.

```python
def configure_domain(
    project_id: str,
    service_id: str,
    domain: str,
    enable_ssl: bool = True
) -> DomainConfig
```

---

#### `delete_deployment()`

Delete a deployment (requires confirmation).

```python
def delete_deployment(
    project_id: str,
    confirm: bool = False
) -> bool
```

---

#### `get_metrics()`

Get resource usage metrics.

```python
def get_metrics(
    project_id: str,
    service_id: str
) -> ResourceMetrics
```

---

#### `list_projects()`

List all Railway projects.

```python
def list_projects() -> List[Dict[str, Any]]
```

## 🔧 MCP Tools Reference

The following tools are available when using this package as an MCP server:

| Tool Name | Description | Required Parameters |
|-----------|-------------|---------------------|
| `deploy_openwebui` | Deploy a new OpenWebUI instance | `project_name` |
| `get_deployment_status` | Get deployment status | `project_id` |
| `update_deployment` | Update existing deployment | `project_id`, `service_id` |
| `scale_deployment` | Scale resources | `project_id`, `service_id` |
| `get_logs` | Retrieve logs | `project_id`, `service_id` |
| `configure_domain` | Add custom domain | `project_id`, `service_id`, `domain` |
| `delete_deployment` | Delete deployment | `project_id`, `confirm` |
| `list_projects` | List all projects | None |
| `get_metrics` | Get resource metrics | `project_id`, `service_id` |

### Data Classes

```python
@dataclass
class Deployment:
    id: str
    project_id: str
    service_id: str
    url: str
    status: str
    created_at: datetime
    region: str
    environment: str

@dataclass
class DeploymentStatus:
    status: str  # "running", "deploying", "failed", "stopped"
    health: str  # "healthy", "unhealthy", "unknown"
    uptime: timedelta
    last_deployed: datetime
    current_version: str

@dataclass
class ResourceMetrics:
    cpu_usage_percent: float
    memory_usage_mb: int
    memory_limit_mb: int
    bandwidth_in_mb: float
    bandwidth_out_mb: float
    request_count: int

@dataclass
class DomainConfig:
    domain: str
    ssl_enabled: bool
    dns_configured: bool
    dns_records: List[Dict[str, str]]

@dataclass
class ScaleResult:
    success: bool
    replicas: int
    cpu_limit: float
    memory_limit_mb: int
```

## 📋 Deployment Templates

### Basic OpenWebUI (SQLite)

```python
client.deploy_openwebui(
    project_name="simple-openwebui",
    database_type="sqlite",
    redis_enabled=False
)
```

### Production Setup (PostgreSQL + Redis)

```python
client.deploy_openwebui(
    project_name="production-openwebui",
    database_type="postgresql",
    redis_enabled=True,
    enable_signup=False,
    custom_env={
        "WEBUI_AUTH": "true",
        "ENABLE_COMMUNITY_SHARING": "false"
    }
)
```

### OpenWebUI with Ollama Connection

```python
client.deploy_openwebui(
    project_name="ollama-openwebui",
    custom_env={
        "OLLAMA_BASE_URL": "https://your-ollama.railway.app",
        "ENABLE_OLLAMA_API": "true"
    }
)
```

### OpenWebUI with OpenAI

```python
client.deploy_openwebui(
    project_name="openai-webui",
    custom_env={
        "OPENAI_API_KEY": "sk-your-api-key",
        "OPENAI_API_BASE_URL": "https://api.openai.com/v1",
        "DEFAULT_MODELS": "gpt-4,gpt-3.5-turbo"
    }
)
```

### Multi-Provider Setup

```python
client.deploy_openwebui(
    project_name="multi-provider-webui",
    custom_env={
        "OLLAMA_BASE_URL": "https://ollama.example.com",
        "OPENAI_API_KEY": "sk-your-key",
        "ANTHROPIC_API_KEY": "sk-ant-your-key",
        "ENABLE_RAG_WEB_SEARCH": "true",
        "RAG_WEB_SEARCH_ENGINE": "duckduckgo"
    }
)
```

## 🐛 Troubleshooting

### Common Issues

#### Authentication Error

```
AuthenticationError: Invalid Railway API token
```

**Solution:** Verify your Railway API token is correct and has not expired. Generate a new token at [Railway Dashboard](https://railway.app/account/tokens).

#### Deployment Failed

```
DeploymentError: Deployment failed to start
```

**Solutions:**
1. Check logs: `client.get_logs(project_id, service_id)`
2. Verify environment variables
3. Ensure you have sufficient Railway credits

#### Rate Limit Exceeded

```
RateLimitError: API rate limit exceeded
```

**Solution:** Wait for the rate limit window to reset (usually 1 minute).

### Debug Mode

Enable debug logging:

```python
import logging
logging.basicConfig(level=logging.DEBUG)

client = RailwayOpenWebUI(api_token="your_token", debug=True)
```

### Getting Help

1. Check the [Railway Documentation](https://docs.railway.app)
2. Check the [OpenWebUI Documentation](https://docs.openwebui.com)
3. Open an issue on this repository

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/chad-atexpedient/Railway-OpenwebUI-Tool.git
cd Railway-OpenwebUI-Tool

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check .
black --check .
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [OpenWebUI](https://github.com/open-webui/open-webui) - The amazing self-hosted LLM interface
- [Railway](https://railway.app) - Simple and powerful cloud platform
- [Model Context Protocol](https://modelcontextprotocol.io) - For enabling AI tool integration

---

<p align="center">
  Made with ❤️ for the AI community
  <br>
  <a href="https://github.com/chad-atexpedient/Railway-OpenwebUI-Tool">⭐ Star this repo</a> if you find it useful!
</p>