# OpenWebUI MCP Server
A Model Context Protocol (MCP) server for managing projects, notes, and knowledge bases in [OpenWebUI](https://github.com/open-webui/open-webui).
## Overview
`open-webui-mcp` provides a bridge between LLMs and your OpenWebUI workspace. It allows models to:
- List and manage projects.
- Create and update project-specific notes.
- Associate knowledge bases with projects.
- Propose and apply updates to project configurations based on chat history.
- Upload files directly to knowledge bases.
## Prerequisites
- [Bun](https://bun.sh/) (v1.0+)
- [OpenWebUI](https://github.com/open-webui/open-webui) instance
- [OpenRouter](https://openrouter.ai/) API key
## Quick Start
1. Clone and install:
```bash
git clone https://github.com/your-repo/open-webui-mcp.git
cd open-webui-mcp
bun install
```
2. Configure environment variables:
```bash
export OPENWEBUI_BASE_URL="http://localhost:3000"
export OPENWEBUI_API_KEY="your-api-key"
export OPENROUTER_API_KEY="your-openrouter-key"
```
3. Build and run:
```bash
bun run build
bun run start
```
## Project Mapping
The server uses a `projects.json` file to map project IDs to OpenWebUI folders and resources. This allows for a structured way to manage project-specific context.
### Example `projects.json`
```json
{
"version": "1.0",
"projects": [
{
"id": "project-1",
"name": "My Project",
"folder_id": "folder-uuid",
"note_ids": [],
"knowledge_base_ids": []
}
]
}
```
## Safety Model (Propose/Evaluate/Apply)
To ensure safe updates to project configurations, the server implements a three-step workflow:
1. **Propose**: The model analyzes a conversation and generates a `ProposedChangeSet`.
2. **Evaluate**: An LLM (via OpenRouter) evaluates the proposal for safety and relevance, assigning a score (0-1).
3. **Apply**: If the proposal is deemed safe (score > threshold), it can be applied to the project.
## Documentation
- [Setup Guide](docs/SETUP.md)
- [Tool Reference](docs/TOOLS.md)
## Troubleshooting
- **Connection Errors**: Ensure `OPENWEBUI_BASE_URL` is accessible and the API key is correct.
- **Permission Denied**: Check if your OpenWebUI API key has sufficient permissions to manage folders, notes, and knowledge bases.
- **Evaluation Failures**: Ensure your `OPENROUTER_API_KEY` is valid and has credits.
- **Missing Projects**: Verify that `projects.json` exists in your `DATA_DIR` and is valid JSON.
