openwebui-mcp-server 0.2.0

MCP server for managing Open WebUI - users, groups, models, knowledge bases, and more

Open WebUI MCP Server

An MCP (Model Context Protocol) server that exposes Open WebUI's admin APIs as tools, allowing AI assistants to manage users, groups, models, knowledge bases, and more.

Features

• User Management: List, get, update roles, delete users
• Group Management: Create, update, add/remove members, delete groups
• Model Management: Create custom models, update system prompts, manage parameters
• Knowledge Base Management: Create, list, delete knowledge bases
• Chat Management: List, view, delete chats
• Tool & Function Discovery: List available tools and functions
• Permission-Aware: All operations respect the logged-in user's permissions

Security

Important: This server passes through the user's authentication token to Open WebUI. This means:

• Admin operations require admin API keys
• Regular users can only access their own resources
• All permission checks are enforced by Open WebUI's API

Installation

Package not yet publicly published to pypi.org Use a local development version (see Development)

pip install openwebui-mcp-server

Or with uv:

uv pip install openwebui-mcp-server

Configuration

Set the required environment variable:

export WEBUI_URL=https://your-openwebui-instance.com

Optionally, set a default API key (can be overridden per-request):

export WEBUI_API_KEY=your-api-key

Usage

With Claude Desktop

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "openwebui": {
      "command": "openwebui-mcp",
      "env": {
        "WEBUI_URL": "https://your-openwebui-instance.com",
        "WEBUI_API_KEY": "your-api-key"
      }
    }
  }
}

With Open WebUI (via MCPO)

1. Start the server in HTTP mode:

export WEBUI_URL=https://your-openwebui-instance.com
export MCP_TRANSPORT=http
export MCP_HTTP_PORT=8001
openwebui-mcp

1. Add as MCP server in Open WebUI:
   • Go to Admin Settings → External Tools
   • Add new MCP server with URL: http://localhost:8001/mcp

Programmatic Usage

from openwebui_mcp.client import OpenWebUIClient

client = OpenWebUIClient(
    base_url="https://your-openwebui-instance.com",
    api_key="your-api-key"
)

# List all users (admin only)
users = await client.list_users()

# Create a group
group = await client.create_group("Engineering", "Engineering team")

# Create a custom model
model = await client.create_model(
    id="my-assistant",
    name="My Assistant",
    base_model_id="gpt-4",
    meta={"system": "You are a helpful assistant."},
    params={"temperature": 0.7}
)

Available Tools

User Management

Tool	Description	Permission
get_current_user	Get authenticated user's profile	Any
list_users	List all users	Admin
get_user	Get specific user details	Admin
update_user_role	Change user role	Admin
delete_user	Delete a user	Admin

Group Management

Tool	Description	Permission
list_groups	List all groups	Any
create_group	Create a new group	Admin
get_group	Get group details	Any
update_group	Update group name/description	Admin
add_user_to_group	Add user to group	Admin
remove_user_from_group	Remove user from group	Admin
delete_group	Delete a group	Admin

Model Management

Tool	Description	Permission
list_models	List all models	Any
get_model	Get model configuration	Any
create_model	Create custom model	Admin
update_model	Update model settings	Admin
delete_model	Delete a model	Admin

Knowledge Base Management

Tool	Description	Permission
list_knowledge_bases	List knowledge bases	Any
get_knowledge_base	Get knowledge base details	Any
create_knowledge_base	Create knowledge base	Any
delete_knowledge_base	Delete knowledge base	Owner

Chat Management

Tool	Description	Permission
list_chats	List user's chats	Own
get_chat	Get chat messages	Own
delete_chat	Delete a chat	Own
delete_all_chats	Delete all chats	Own

System

Tool	Description	Permission
list_tools	List available tools	Any
list_functions	List functions/filters	Any
get_system_config	Get system config	Admin

Development

# Clone the repo
git clone https://github.com/troylar/open-webui-mcp-server.git
cd open-webui-mcp-server

# Install dev dependencies and the package itself 
pip install -e ".[dev]"

or using uv:

# Install dependencies (with optional dev dependencies)
uv lock && uv sync --extra="dev"

# Install the project as a package in editable mode (using optional dev dependencies)
uv pip install -e ".[dev]"

# Check your new executable
which openwebui-mcp
open-webui-mcp-server/.venv/bin/openwebui-mcp

Linter

# Run linter
ruff --config pyproject.toml check src/
# Fix linting issues
ruff --config pyproject.toml check --fix src/

Tests

# Run tests
pytest tests;
# or via `uv`  
uv run pytest tests/ -v;

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

Consider for adoption

• OWUI Python Client (docs)
• Github Workflows to PyPi.org

Related Projects

• Open WebUI - The web UI this server manages
• FastMCP - The MCP framework used
• MCPO - MCP to OpenAPI proxy