OpenWebUI MCP Server

A Model Context Protocol (MCP) server for managing projects, notes, and knowledge bases in OpenWebUI.

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 (v1.0+)
OpenWebUI instance
OpenRouter API key

Quick Start

Clone and install:

git clone https://github.com/your-repo/open-webui-mcp.git
cd open-webui-mcp
bun install

Configure environment variables:

export OPENWEBUI_BASE_URL="http://localhost:3000"
export OPENWEBUI_API_KEY="your-api-key"
export OPENROUTER_API_KEY="your-openrouter-key"

Build and run:
```
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`

{
  "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:

Propose: The model analyzes a conversation and generates a ProposedChangeSet.
Evaluate: An LLM (via OpenRouter) evaluates the proposal for safety and relevance, assigning a score (0-1).
Apply: If the proposal is deemed safe (score > threshold), it can be applied to the project.

Documentation

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.