Open Webui Knowledge Server

An MCP (Model Context Protocol) server that exposes 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

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):

npx .

Usage

stdio mode (Local)

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)

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

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:

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

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

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:

/mcp

You should see open-webui-knowledge listed with a green status indicator.

Uninstall

To remove the MCP server from Claude Code:

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 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 for development setup and guidelines.

License

This project is licensed under the MIT License.

---