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

1. Clone and install:

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

2. Configure environment variables:

   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:

   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:

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

• Tool Reference

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.