# Setup Guide
This document provides instructions for setting up and configuring the `open-webui-mcp` server.
## Prerequisites
- [Bun](https://bun.sh/) (v1.0 or later)
- An active [OpenWebUI](https://github.com/open-webui/open-webui) instance
- An [OpenRouter](https://openrouter.ai/) API key (for the safety evaluation model)
## Installation
1. Clone the repository:
```bash
git clone https://github.com/your-repo/open-webui-mcp.git
cd open-webui-mcp
```
2. Install dependencies:
```bash
bun install
```
3. Build the project:
```bash
bun run build
```
## Configuration
The server is configured using environment variables. You can set these in your shell or in a `.env` file.
### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `OPENWEBUI_BASE_URL` | Yes | - | The base URL of your OpenWebUI instance (e.g., `http://localhost:3000`). |
| `OPENWEBUI_API_KEY` | Yes | - | Your OpenWebUI API key. |
| `OPENROUTER_API_KEY` | Yes | - | Your OpenRouter API key. |
| `OPENROUTER_MODEL` | No | `openai/gpt-4o-mini` | The LLM model to use for safety evaluation. |
| `OPENROUTER_SCORE_THRESHOLD` | No | `0.8` | The minimum score (0-1) required for a proposal to be considered safe. |
| `DATA_DIR` | No | `./data` | The directory where `projects.json` and audit logs are stored. |
## Project Configuration (`projects.json`)
The server requires a `projects.json` file in your `DATA_DIR` to map projects to OpenWebUI folders and resources.
### Example `projects.json`
```json
{
"version": "1.0",
"projects": [
{
"id": "project-1",
"name": "My Project",
"description": "A sample project",
"folder_id": "folder-uuid-from-openwebui",
"note_ids": [],
"knowledge_base_ids": []
}
]
}
```
## Running the Server
To start the server using `stdio` transport (standard for MCP):
```bash
bun run start
```
## Integration with OpenWebUI
To use this MCP server in OpenWebUI, add it to your MCP configuration:
1. Go to **Settings > Workspace > MCP**.
2. Add a new server with the following command:
```bash
bun run /path/to/open-webui-mcp/dist/index.js
```
3. Ensure the environment variables are available to the process running OpenWebUI.
