Open WebUI Knowledge Base MCP Server

<div align="center">

MCP server for Open WebUI Knowledge Bases – Search and access your knowledge bases from Cursor, Claude Desktop, and other MCP clients

Features • Quick Start • Usage • Available Tools • Contributing

</div>

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.

---

<div align="center">

Built with ❤️ by Ronas IT

Professional development services • Open source contributors

Website • GitHub • Email

</div>