owui-bash-mcp

Single-endpoint FastAPI OpenAPI tool server that gives Open WebUI a bash tool for coding. Runs as the dedicated unix user owui-coder, confined to a persistent projects workspace.

Endpoint

POST /run_bash — { command, cwd?, timeout? } → { stdout, stderr, exit_code, timed_out, truncated, cwd }. Runs bash -lc <command> in PROJECTS_ROOT/<cwd>. Filesystem state persists between calls; cwd does not (pass it each call).

Related MCP server: Terminal MCP Server

Config (env)

• BASH_MCP_PROJECTS_ROOT (default /home/owui-coder/projects)

• BASH_MCP_DEFAULT_TIMEOUT (300s), BASH_MCP_MAX_TIMEOUT (1800s)

• BASH_MCP_MAX_OUTPUT (100000 bytes/stream, tail kept)

Run

uvicorn app:app --host 127.0.0.1 --port 8774 (8770–8773 are already taken on this host by proton-mcp / mcpo.)

Deploy

systemd system unit owui-bash-mcp.service (User=owui-coder), registered in OWUI as tool server http://127.0.0.1:8774. See diverse/deploy.

Test

BASH_MCP_PROJECTS_ROOT=/tmp/owui-bash-test-root .venv/bin/pytest (venv built with uv venv --python 3.13).