Bitrix MCP Server for OpenWebUI

This repository contains a Docker-based Python MCP OAuth bridge for OpenWebUI and Bitrix.

Components

• Dockerfile and docker-compose.yml for containerized deployment

• app/main.py - FastAPI application exposing MCP and OAuth bridge endpoints

• app/bitrix.py - Bitrix OAuth and API helper functions

• app/store.py - local OAuth client and short-lived authorization-state persistence

Related MCP server: bitrix24-mcp-server

Setup

1. Open inbound TCP ports 80 and 443 in the VPS firewall/security group. The public IP must be directly assigned to this VPS.

2. Copy environment values into a .env file (Docker Compose loads it automatically).

3. Set BITRIX_CLIENT_ID, BITRIX_CLIENT_SECRET, PUBLIC_HOST, ACME_EMAIL, TEMPLATE_ENCRYPTION_KEY, SQLITE_ADMIN_USERNAME, and SQLITE_ADMIN_PASSWORD. Set PUBLIC_HOST to the public IPv4 address only, without https://, a port, or a path. For this VPS it is 147.45.38.205.

4. Start the stack with:

docker compose up -d --build

Caddy is the public TLS endpoint. On its first boot it temporarily serves only the ACME challenge on port 80; Certbot obtains a publicly trusted, six-day Let's Encrypt certificate for PUBLIC_HOST, then Caddy starts HTTPS and redirects HTTP to it. Certbot checks renewal every 12 hours and reloads Caddy through a private Unix socket. The FastAPI container remains private inside the Docker network. Do not publish port 8080.

SQLite inspector

/sqlite is served by the dedicated sqlite-web container rather than the MCP application. It provides schema browsing, pagination, exports, and SQL queries, but receives the live database through a read-only volume.

Open:

https://147.45.38.205/sqlite

The browser prompts for SQLITE_ADMIN_USERNAME and SQLITE_ADMIN_PASSWORD from .env. Caddy derives a bcrypt hash inside its container; the plaintext password is never placed in the Caddyfile. The database-client port is not published publicly.

OWU integration

OpenWebUI registers a unique OAuth client with this server at POST /register. It then uses this server's /authorize and /token endpoints, discovered from /.well-known/oauth-authorization-server. The bridge redirects the user to the official Bitrix authorization page, exchanges the Bitrix authorization code server-side, and returns the resulting access/refresh tokens to OpenWebUI. OpenWebUI stores and refreshes those per-user tokens; tool calls use the bearer token forwarded by OpenWebUI to POST /mcp. The server provides users_list, create_task, and get_user_info; their MCP descriptions and schemas are in Russian for use by Russian-language models.

Register exactly this callback URL in the Bitrix OAuth application:

<BASE_URL>/oauth/callback

For this VPS, that is:

https://147.45.38.205/oauth/callback

Update the Bitrix local application's callback URL to this HTTPS URL, then update the OpenWebUI MCP connection URL to:

https://147.45.38.205/mcp

Codespaces hosting

This app is ready to run in GitHub Codespaces. Expose port 8080 in Codespaces, then use the generated public URL to reach /mcp.

If GitHub shows an intermediate alert page for the public dev URL, continue through it in the browser so the real app endpoint is reachable.

OAuth flow

1. OpenWebUI dynamically registers at /register.

2. OpenWebUI redirects the user to this server's /authorize endpoint.

3. The bridge redirects the user to official Bitrix authentication.

4. Bitrix redirects to /oauth/callback; the bridge exchanges its code and sends a one-time authorization code back to OpenWebUI.

5. OpenWebUI exchanges that code at /token, stores the returned Bitrix tokens, and refreshes them through /token when needed.

Example tool call

curl -X POST https://147.45.38.205/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <bitrix-access-token>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_user_info","arguments":{}}}'