# Open WebUI Knowledge Base MCP Server
[](https://github.com/RonasIT/open-webui-mcp-server/actions/workflows/validate.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) • [Instructing AI](#instructing-ai-to-use-knowledge-bases) • [Contributing](CONTRIBUTING.md)
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** – stdio (local) and HTTP (remote)
- 🔒 **Secure** – Per-connection auth, input validation, rate limiting, CORS protection
## Quick Start
### Prerequisites
- Node.js 22+ or Docker
- Open WebUI instance with API access
- API token from Open WebUI (Settings → Account → API keys)
### Run with NPX
```bash
export OPEN_WEBUI_API_URL="https://your-open-webui-instance.com/api/v1"
export OPEN_WEBUI_API_TOKEN="sk-your-token-here"
npx open-webui-knowledge-mcp-server
```
Or from the repo (after `npm install` and `npm run build`):
```bash
npx .
```
## 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"
npx open-webui-knowledge-mcp-server
```
### HTTP mode (Production)
```bash
export OPEN_WEBUI_API_URL="https://your-open-webui-instance.com/api/v1"
export MCP_TRANSPORT=http
export MCP_HTTP_PORT=8001
npx open-webui-knowledge-mcp-server
```
Server endpoints:
- **MCP**: `http://localhost:8001/mcp`
- **Health**: `http://localhost:8001/health`
### Docker
```bash
docker build -t open-webui-mcp-server .
docker run -e OPEN_WEBUI_API_URL=https://your-instance.com/api/v1 -e OPEN_WEBUI_API_TOKEN=sk-xxx -p 8001:8001 open-webui-mcp-server
```
## Configuring Cursor to use your MCP server
### Cursor: stdio mode
Edit `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"open-webui-knowledge": {
"command": "npx",
"args": ["open-webui-knowledge-mcp-server"],
"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": "https://your-remote-server-url/mcp",
"headers": {
"Authorization": "Bearer sk-your-token-here"
}
}
}
}
```
## Configuring Claude Code to use your MCP server
### Installation
```bash
claude mcp add open-webui-knowledge --scope user \
-e OPEN_WEBUI_API_URL=https://your-open-webui-instance.com/api/v1 \
-e OPEN_WEBUI_API_TOKEN=sk-your-token-here \
-- npx -y open-webui-knowledge-mcp-server
```
### Verify the connection
Start Claude Code and check that the MCP server is running:
```bash
/mcp
```
You should see `open-webui-knowledge` listed with a green status indicator.
### Uninstall
To remove the MCP server from Claude Code:
```bash
claude mcp remove open-webui-knowledge
```
## 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
## Instructing AI to use knowledge bases
After the MCP server is configured in Cursor or Claude Desktop, the assistant can call the tools but may not know **when** to use them or **which** knowledge base to query. You can give it explicit instructions so it prefers your knowledge bases for internal docs, standards, and architecture.
1. **Use the provided template**
Copy [AGENTS-template.md](AGENTS-template.md) into a place your AI reads:
- **Cursor:** Copy to `AGENTS.md` in the project root, or add its contents to `.cursor/rules` or project rules in Cursor settings.
- **Claude Desktop / other clients:** Paste the instructions into your custom instructions or system prompt.
2. **Customize the template**
- Adjust the “When to query” section to match your domains (e.g. which base to use for frontend, backend, sales).
- Describe other keywords/conditions to instruct AI to call your knowledge bases via MCP.
3. **Keep it updated**
The template tells the AI to call **list_knowledge_bases** when unsure and to update the table when bases change, so the reference stays accurate.
## Environment Variables
| Variable | Description | Default |
| -------------------------- | ---------------------------------------------- | ------------- |
| `OPEN_WEBUI_API_URL` | Open WebUI API base URL | Required |
| `OPEN_WEBUI_API_TOKEN` | Default API token (optional in HTTP) | 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**.
---
**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)