Open WebUI Knowledge Base MCP Server

An MCP (Model Context Protocol) server that exposes Open WebUI Knowledge Bases as tools and resources, enabling AI assistants like Cursor and Claude Desktop to search and access knowledge bases.

Features

• 🔍 Semantic Search - Search knowledge bases using semantic search
• 📚 Knowledge Base Management - List and get information about knowledge bases
• 👥 Multi-User Support - Each connection uses its own API token for isolation
• 🌐 Dual Transport Modes - Supports both stdio (local) and HTTP (remote) transports
• 🔒 Secure - Per-connection authentication, input validation, rate limiting, CORS protection

Quick Start

Prerequisites

• Python 3.8+ or Docker
• Open WebUI instance with API access
• API token from Open WebUI (Settings → Account → API keys)

Installation

pip install -r requirements.txt

Or using uvx:

pip install uv  # or: brew install uv
uvx --from . python mcp_server.py

Usage

stdio Mode (Local)

export OPEN_WEBUI_API_URL="https://your-open-webui-instance.com/api/v1"
export OPEN_WEBUI_API_TOKEN="sk-your-token-here"
python mcp_server.py

HTTP Mode (Production)

Docker Compose:

# Create .env file
echo "OPEN_WEBUI_API_URL=https://your-open-webui-instance.com/api/v1" > .env

# Start server
docker-compose up -d

# View logs
docker-compose logs -f

Direct Python:

export OPEN_WEBUI_API_URL="https://your-open-webui-instance.com/api/v1"
export MCP_TRANSPORT="http"
export MCP_HTTP_PORT="8001"
python mcp_server.py

Server endpoints:

• MCP: http://localhost:8001/mcp
• Health: http://localhost:8001/health

Configuring Cursor to use your MCP server

Cursor: stdio Mode

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "open-webui-knowledge": {
      "command": "uvx",
      "args": ["--from", "/path/to/open-webui-mcp-server", "python", "/path/to/open-webui-mcp-server/mcp_server.py"],
      "env": {
        "OPEN_WEBUI_API_URL": "https://your-open-webui-instance.com/api/v1",
        "OPEN_WEBUI_API_TOKEN": "sk-your-token-here"
      }
    }
  }
}

Cursor: HTTP Mode

{
  "mcpServers": {
    "open-webui-knowledge": {
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer sk-your-token-here"
      }
    }
  }
}

Available Tools

• list_knowledge_bases - List all accessible knowledge bases

  • permission (optional): "read" or "write" (default: "read")

• search_knowledge_base - Search a knowledge base using semantic search

  • knowledge_base_id (required): The ID of the knowledge base
  • query (required): Your search query
  • k (optional): Number of results (default: 5)

• get_knowledge_base_info - Get detailed information about a knowledge base

  • knowledge_base_id (required): The ID of the knowledge base

Environment Variables

Security

• Input validation and sanitization
• Rate limiting (per-IP and per-token)
• CORS protection (disabled by default)
• Request size limits (10MB max)
• Error message sanitization
• Token validation

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

This project is licensed under the MIT License.