🚂 Railway OpenWebUI MCP Tool

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

📋 Table of Contents

• Overview
• Features
• Prerequisites
• Installation
• Configuration
• Usage
• API Reference
• MCP Tools Reference
• Deployment Templates
• Troubleshooting
• Contributing
• 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 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 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) 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)

pip install railway-openwebui-mcp

Option 2: From source

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

Option 3: Docker

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

Option 4: Using uvx (no installation)

uvx railway-openwebui-mcp

⚙️ Configuration

1. Get Railway API Token

1. Go to Railway Dashboard
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:

# 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

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

Using uvx (recommended for Claude Desktop)

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

🚀 Usage

Quick Start (Python Library)

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

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

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

# 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.

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.

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

---

update_deployment()

Update an existing deployment.

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.

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.

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.

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

---

delete_deployment()

Delete a deployment (requires confirmation).

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

---

get_metrics()

Get resource usage metrics.

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

---

list_projects()

List all Railway projects.

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

@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)

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

Production Setup (PostgreSQL + Redis)

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

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

OpenWebUI with OpenAI

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

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.

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:

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

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

Getting Help

1. Check the Railway Documentation
2. Check the OpenWebUI Documentation
3. Open an issue on this repository

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Setup

# 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 file for details.

🙏 Acknowledgments

• OpenWebUI - The amazing self-hosted LLM interface
• Railway - Simple and powerful cloud platform
• Model Context Protocol - 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>