Open WebUI Knowledge Base 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

• 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

Variable	Description	Default
OPEN_WEBUI_API_URL	Open WebUI API base URL	Required
OPEN_WEBUI_API_TOKEN	Default API token (optional)	None
MCP_TRANSPORT	Transport mode: stdio or http	stdio
MCP_HTTP_HOST	HTTP server host	0.0.0.0
MCP_HTTP_PORT	HTTP server port	8001
MCP_CORS_ORIGINS	Comma-separated CORS origins (empty = no CORS)	Empty
MCP_RATE_LIMIT_PER_IP	Rate limit per IP (e.g., "1000/minute")	1000/minute
MCP_RATE_LIMIT_PER_TOKEN	Rate limit per token	1000/minute
MCP_RATE_LIMIT_HEALTH	Rate limit for health endpoint	10/minute

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.

---