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 LICENSE 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