Open WebUI

You can manage users, groups, models, knowledge bases, chats, and more through the Open WebUI MCP Server. It exposes admin APIs as tools, enabling an AI assistant to perform administrative and configuration tasks with proper permission checks.

How to use

You interact with the Open WebUI MCP Server through an MCP client. Start by running the MCP server in HTTP mode, then connect your client to the provided MCP URL. You can perform operations such as listing users, creating groups, managing models, and handling knowledge bases. All actions respect your permissions as enforced by Open WebUI.

How to install

Prerequisites: Python and a working Python environment. You will install the MCP server package and then run it in HTTP mode.

pip install openwebui-mcp-server

# Alternative using uvx runner
uv pip install openwebui-mcp-server

Configuration and security

Configure the server to point to your Open WebUI instance and provide an API key if needed. The server forwards your authentication token to Open WebUI, so admin operations require admin API keys and regular users can only access their own resources.

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

Optional per-request API key override:

export OPENWEBUI_API_KEY=your-api-key

Usage with Open WebUI (MCPO)

If you are using Open WebUI with MCPO, first start the MCP server in HTTP mode, then register it as an external MCP server in Open WebUI.

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

Then add the MCP server in Open WebUI with the URL http://localhost:8001/mcp.

Programmatic usage

You can interact with the MCP server from code using a client library. The example below demonstrates listing users, creating a group, and creating a custom model.

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

Notes and troubleshooting

If you encounter connection issues, verify that OPENWEBUI_URL is reachable from the MCP host and that the MCP HTTP port is open. Ensure your API keys and permissions align with the tasks you attempt to perform.

Available tools

get_current_user

Get authenticated user's profile

list_users

List all users

get_user

Get specific user details

update_user_role

Change user role

delete_user

Delete a user

list_groups

List all groups

create_group

Create a new group

get_group

Get group details

update_group

Update group name/description

add_user_to_group

Add user to group

remove_user_from_group

Remove user from group

delete_group

Delete a group

list_models

List all models

get_model

Get model configuration

create_model

Create custom model

update_model

Update model settings

delete_model

Delete a model

list_knowledge_bases

List knowledge bases

get_knowledge_base

Get knowledge base details

create_knowledge_base

Create knowledge base

delete_knowledge_base

Delete knowledge base

list_chats

List user's chats

get_chat

Get chat messages

delete_chat

Delete a chat

delete_all_chats

Delete all chats

list_tools

List available tools

list_functions

List functions/filters

get_system_config

Get system config