open-webui-mcp-server by troylar - MCP Server

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

pip install openwebui-mcp-server

Or with uv:

uv pip install openwebui-mcp-server

Configuration

Set the required environment variable:

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

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

export OPENWEBUI_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": {
        "OPENWEBUI_URL": "https://your-openwebui-instance.com",
        "OPENWEBUI_API_KEY": "your-api-key"
      }
    }
  }
}

With Open WebUI (via MCPO)

Start the server in HTTP mode:

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

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
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check src/

License

MIT License - see for details.

Contributing

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

Related Projects

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