# Open WebUI Knowledge Base MCP Server

<div align="center">

![Open WebUI](https://img.shields.io/badge/Open%20WebUI-0.7.2+-green.svg)
![Transport](https://img.shields.io/badge/transport-stdio%20%7C%20HTTP-lightgrey.svg)
![Python](https://img.shields.io/badge/python-3.8+-blue.svg)
[![Tests](https://github.com/RonasIT/open-webui-mcp-server/actions/workflows/tests.yml/badge.svg)](https://github.com/RonasIT/open-webui-mcp-server/actions/workflows/tests.yml)

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

[Features](#features) • [Quick Start](#quick-start) • [Usage](#usage) • [Available Tools](#available-tools) • [Contributing](CONTRIBUTING.md)

</div>

An MCP (Model Context Protocol) server that exposes [Open WebUI](https://github.com/open-webui/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

```bash
pip install -r requirements.txt
```

Or using `uvx`:

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

## Usage

### stdio Mode (Local)

```bash
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:**

```bash
# 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:**

```bash
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`:

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

```json
{
  "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](CONTRIBUTING.md) for development setup and guidelines.

## License

This project is licensed under the **MIT License**.

---

<div align="center">

**Built with ❤️ by [Ronas IT](https://ronasit.com)**

_Professional development services • Open source contributors_

[Website](https://ronasit.com) • [GitHub](https://github.com/RonasIT) • [Email](mailto:hello@ronasit.com)

</div>