owui MCP

owui_mcp

owui_mcp 是一个 模型上下文协议（MCP） 服务器（stdio）公开 打开WebUI API 作为MCP 工具，通过包装Python客户端库 owui_client （原版的叉子）。

这个repo故意是一个薄包装器： 真理的源泉在于 owui_client.何时 owui_client 添加/更改端点， owui_mcp 启动时自动拾取它们。

注： 这 owui_client 分叉代码直接提供到这个包中(src/owui_client/)因此在安装时不需要外部git依赖。

基础项目：owui_client

• 叉子：https://github.com/adaofeliz/owui_client（基于https://github.com/whogben/owui_client)
• PyPI： pip install owui-client
• 文件：https://whogben.github.io/owui_client/

owui_client 是一个完全类型化的异步客户端，它反映了Open WebUI的后端路由器结构(client.chats.*, client.models.*, client.tools.*等等）。

运作原理

在启动时， owui_mcp:

1. 创建一个 owui_client.OpenWebUI 使用env变量的实例(OWUI_API_URL, OWUI_API_KEY)
2. 反思客户端的路由器（所有 ResourceBase 路由器）
3. 寄存器 每个公共异步方法 作为MCP工具，使用 FastMCP
4. FastMCP根据Python类型提示和Pydantic模型自动生成工具输入模式 owui_client
5. 可选启用 代码模式 通过 --code-mode flag，一种FastMCP转换，为发现和沙盒代码执行提供元工具。默认情况下关闭；没有它，所有工具都直接暴露在外。

工具命名

每个工具都命名为：

{router}__{method}

示例：

• auths__get_session_user
• chats__search
• models__get_models
• knowledge__create_new_knowledge

需求

• python 3.10+
• Open WebUI实例（本地或远程）
• API密钥/承载令牌（推荐）

安装

来源（此仓库）

pip install -e .

来自PyPI（如果已发布）

pip install owui-mcp

配置

如果 OWUI_API_KEY 如果未设置，服务器仍将运行，但请求可能会失败，具体取决于您的Open WebUI配置。

运行（stdio MCP服务器）

通常， 您的MCP客户端 （克劳德桌面/光标）启动服务器。对于本地调试，您可以运行：

# Default: all tools exposed directly (recommended)
OWUI_API_URL="http://localhost:8080/api" \
OWUI_API_KEY="sk-..." \
owui-mcp

# With Code Mode: meta-tools for discovery + sandboxed code execution
OWUI_API_URL="http://localhost:8080/api" \
OWUI_API_KEY="sk-..." \
owui-mcp --code-mode

或者：

python -m owui_mcp

注意：MCP stdio服务器必须保持 标准输出 为协议保留。此项目登录到 标准错误.

MCP束（MCPB）

您可以使用MCPB CLI在本地构建MCP捆绑包：

npx --yes @anthropic-ai/mcpb validate .
npx --yes @anthropic-ai/mcpb pack . owui-mcp.mcpb

最新的捆绑包也可作为GitHub Release资产下载 owui-mcp.mcpb 从 发布 页面。

连接到克劳德桌面（MCP）

Claude Desktop从以下位置读取MCP服务器定义 claude_desktop_config.json.

配置文件位置

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

参考：https://modelcontextprotocol.io/docs/develop/connect-local-servers

最小配置（推荐）

{
  "mcpServers": {
    "owui": {
      "command": "owui-mcp",
      "env": {
        "OWUI_API_URL": "http://localhost:8080/api",
        "OWUI_API_KEY": "sk-..."
      }
    }
  }
}

要启用代码模式，请添加 "--code-mode" 到 args 数组：

{
  "mcpServers": {
    "owui": {
      "command": "owui-mcp",
      "args": ["--code-mode"],
      "env": {
        "OWUI_API_URL": "http://localhost:8080/api",
        "OWUI_API_KEY": "sk-..."
      }
    }
  }
}

如果 owui-mcp 在您的 PATH，使用绝对命令路径。

替代配置（最可靠，使用python-m）

使用您希望Claude Desktop运行的Python解释器（venv/pipx/system-Python）：

{
  "mcpServers": {
    "owui": {
      "command": "/ABSOLUTE/PATH/TO/python",
      "args": ["-m", "owui_mcp"],
      "env": {
        "OWUI_API_URL": "http://localhost:8080/api",
        "OWUI_API_KEY": "sk-..."
      }
    }
  }
}

要启用代码模式，请添加 "--code-mode" 到 args 数组（例如。 ["-m", "owui_mcp", "--code-mode"]).

需要重新启动

在编辑配置之后， 完全退出并重新启动 克劳德桌面。

奖金：光标MCP

Cursor支持类似的 mcpServers JSON配置。

• macOS: ~/.cursor/mcp.json
• 视窗: %APPDATA%\.cursor\mcp.json

使用与上述Claude示例相同的服务器定义。

正在更新owui_client

owui_mcp 自动发现 owui_client 启动时的方法。因为分叉是在这个仓库中提供的，所以更新需要将提供的代码插入 src/owui_client/ 并发布新版本。

许可证

麻省理工学院