@bitrix24/mcp-vibecode-api

MCP (Model Context Protocol) server for Bitrix24 via the Vibe API. Gives AI assistants 52 tools to work with CRM deals, contacts, tasks, files, users, and 40+ other entity types — plus portal, key, app, infrastructure, bot, AI-credential, placement, and feedback management.

Quick Start

npx @bitrix24/mcp-vibecode-api --key vibe_app_xxx_yyy_zz

The server connects to https://vibecode.bitrix24.tech by default. Override with --api-url:

npx @bitrix24/mcp-vibecode-api --key vibe_app_xxx_yyy_zz --api-url http://localhost:8000

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vibe-bitrix24": {
      "command": "npx",
      "args": ["-y", "@bitrix24/mcp-vibecode-api", "--key", "vibe_app_xxx_yyy_zz"]
    }
  }
}

For a self-hosted API:

{
  "mcpServers": {
    "vibe-bitrix24": {
      "command": "npx",
      "args": [
        "-y", "@bitrix24/mcp-vibecode-api",
        "--key", "vibe_app_xxx_yyy_zz",
        "--api-url", "http://localhost:8000"
      ]
    }
  }
}

Environment Variables

Instead of CLI flags, you can set environment variables:

| Variable | Flag | Description | |----------|------|-------------| | VIBE_API_KEY | --key | API key (required) | | VIBE_API_URL | --api-url | API base URL (default: https://vibecode.bitrix24.tech) | | VIBE_MCP_HTTP_TOKEN | --http-token | Bearer token required by the HTTP transport |

Tools (52)

Entity Tools (10)

| Tool | Description | |------|-------------| | discover | Get API schema — summary of all 45 entities or full field definitions for one entity | | get_fields | Get live field definitions including user-defined custom fields (UF_*) | | list_entities | List entities with filters, sorting, pagination. Auto-paginates when limit > 50 | | get_entity | Get a single entity by ID | | create_entity | Create a new entity | | update_entity | Update an existing entity (partial update) | | delete_entity | Delete an entity by ID | | search_entities | Search with MongoDB-style filters ($gt, $gte, $lt, $lte, $ne, $contains, $in) | | batch_entities | Batch create, update, and/or delete entities (max 500 items) | | aggregate_entities | Aggregation: count, sum, avg, min, max with groupBy and filter |

Portal Tools (1)

| Tool | Description | |------|-------------| | list_portals | List all portals accessible with the management key |

Me Tools (1)

| Tool | Description | |------|-------------| | get_me | Caller identity, tariff, trial state, capabilities. Supports sections filter and refresh: 'tariff'. The heavy api doc block is always stripped — use the vibe://api-reference resource instead |

Key Tools (6)

| Tool | Description | |------|-------------| | list_keys | List all API keys for a portal | | get_key | Get a specific API key by ID | | create_key | Create a new API key with scopes, IP whitelist, expiration | | update_key | Update an existing API key | | delete_key | Delete an API key permanently | | rotate_key | Rotate an API key, generating a new secret |

App Tools (7)

| Tool | Description | |------|-------------| | list_apps | List all apps, optionally filtered by status | | get_app | Get a specific app by ID | | create_app | Create a new Bitrix24 app (note: handlerUrl is platform-set; configure appUrl for your placement iframe) | | update_app | Update an existing app | | delete_app | Delete an app permanently | | publish_app | Publish an app company-wide (402 returns userMessage/alternatives/hint when the tariff gate trips) | | unpublish_app | Revert an app to draft status |

Placement Tools (1)

| Tool | Description | |------|-------------| | manage_placements | list_bound / list_available / bind / unbind. Enforces IM placements (IM_SIDEBAR, IM_NAVIGATION, IM_TEXTAREA) require options.iconName client-side — the B24 error is opaque |

Deployment Tools (3)

| Tool | Description | |------|-------------| | list_deployments | List all deployments for an app | | deploy_app | Deploy an app to portal or marketplace | | undeploy_app | Remove a specific deployment |

Infra Tools (3)

| Tool | Description | |------|-------------| | manage_server | Core server lifecycle: list, get, create, update, delete, start, stop, reboot, wake, sleep_now, refresh, metrics, port, sleep_config, repair, mode | | manage_server_deploy | Deploy pipeline: deploy, list_deployments, exec, upload, logs. Supports debug: true and cleanDeploy | | manage_server_access | Black Hole access: list_access, add_access, remove_access, b24_users_search (autocomplete) |

Bot Tools (3)

| Tool | Description | |------|-------------| | manage_bot | Bot registry: register, unregister, update, list, get_events | | manage_bot_chat | Chat lifecycle: create, get, update, leave, add_user, remove_user, set_owner | | manage_bot_messages | Message ops: send, edit, delete, add_reaction, remove_reaction, read, get_history |

AI Credential Tools (1)

| Tool | Description | |------|-------------| | manage_ai_credentials | USER-scope BYOK: list, create, update, delete, test, usage, list_providers. create/update verify the key before save and return 422 CREDENTIAL_INVALID when it fails |

Feedback Tools (1)

| Tool | Description | |------|-------------| | manage_feedback | Feedback tickets on /v1/feedback: create / list / get / update / comment. Three access tiers (APP key / vibe:feedback scope / management key). Prefer comment over update for anything user-visible — it posts a thread row, mirrors into resolution, and emails the user. Never flip status to RESOLVED before the fix is deployed |

API Surface Tools (15)

Typed wrappers around the rest of the V1 surface. Prefer these over call_api when available:

| Tool | Description | |------|-------------| | ai_chat | Chat completions via /v1/chat/completions (sync + streaming) | | manage_workday | Work-day start/stop, breaks, status queries | | manage_workflow | Bizproc workflow start, status, tasks | | send_notification | im.notify personal and system notifications | | manage_call | Telephony call register, finish, attach-record | | manage_trigger | CRM automation trigger fire/list | | manage_timeline_log | CRM timeline log comments and entries | | manage_warehouse | Catalog warehouse inventory and documents | | manage_post | Sonet post create/update/delete | | manage_userfield | Custom-field CRUD for CRM types and smart-processes (via /v1/items/:entityTypeId/userfields) | | manage_task_time | Task time tracking | | manage_chat | Chat create/invite/leave via /v1/chats/* (app-wide chat ops, distinct from bot chats) | | crm_extras | Lead-convert, product-rows, and other CRM helpers | | manage_file | File upload/download via /v1/files | | call_api | Escape hatch — direct V1 API call when no typed tool exists |

Supported Entities (45)

deals, contacts, companies, leads, quotes, activities, activity-types, products, product-sections, statuses, currencies, deal-categories, requisites, timelines, invoices, items, smart-processes, tasks, calendar-events, files, folders, storages, users, departments, workgroups, chats, messages, list-elements, catalog-products, catalog-sections, catalog-prices, orders, order-statuses, basket-items, payments, sites, pages, doc-templates, documents, bookings, bizproc-templates, bizproc-activities, bizproc-robots, openline-configs, telephony-lines.

Features

• Auto-pagination — requests with limit > 50 automatically paginate through all results
• Custom fields — get_fields returns user-defined fields (UF_*) alongside static schema fields
• MongoDB-style filters — $gt, $gte, $lt, $lte, $ne, $contains, $in operators in search
• Date windowing — large searches auto-split into date windows for reliability (disable with autoWindow: false)
• Cross-entity batch — combine up to 50 calls across different entities in one request via /v1/batch
• Batch search — action: "search" in batch auto-paginates each sub-call individually (up to 5000 records)
• Aggregation — count, sum, avg, min, max with groupBy support

Transports

• stdio (default) — for Claude Desktop, Cursor, and other MCP clients
• HTTP — --http flag starts an authenticated HTTP server on 127.0.0.1:3001

HTTP mode

The HTTP transport is hardened and requires a Bearer token. Start it with:

npx @bitrix24/mcp-vibecode-api \
  --key vibe_app_xxx_yyy_zz \
  --http \
  --http-token "$(openssl rand -hex 32)" \
  --allowed-origins https://your-client.example.com

Or via environment:

export VIBE_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
npx @bitrix24/mcp-vibecode-api --key vibe_app_xxx --http

Clients call POST http://127.0.0.1:3001/mcp with:

Authorization: Bearer <token>
Content-Type: application/json

HTTP flags

| Flag | Default | Description | |------|---------|-------------| | --http | — | Enable HTTP transport | | --host <host> | 127.0.0.1 | Bind address. Keep loopback unless you know what you're doing | | --port <port> | 3001 | TCP port | | --http-token <token> | — | Required. Bearer token; compared with timingSafeEqual. Falls back to VIBE_MCP_HTTP_TOKEN env | | --allowed-origins <csv> | (empty) | Comma-separated Origin allowlist for browser clients. Empty = no browser origin accepted (non-browser clients with no Origin still work) | | --max-body-kb <n> | 256 | Request body cap in KB | | --rate-limit <rpm> | 300 | Per-IP token-bucket rate limit |

Response codes

| Status | Cause | |--------|-------| | 401 | Missing or invalid Bearer token | | 403 | Host-header mismatch, disallowed Origin, or OPTIONS without allow-listed Origin | | 404 | Path other than /mcp | | 405 | Method other than POST or OPTIONS | | 413 | Body exceeds --max-body-kb | | 415 | Content-Type is not application/json | | 429 | Per-IP rate limit exhausted (sends Retry-After: 60) |

The server exits with an error if --http is set without a token. Tokens are never written to logs; startup only names the source (--http-token flag or VIBE_MCP_HTTP_TOKEN env).

Resources

| URI | Description | |-----|-------------| | vibe://api-reference | Auth, filter syntax, error shape, response format — the api doc block extracted from /v1/me. Read this instead of re-fetching /v1/me each time | | vibe://entity/{plural} | Per-entity field reference for all 45 supported entities (e.g. vibe://entity/deals, vibe://entity/tasks) | | vibe://tariff-gate-reference | 402 tariff-gate error codes with userMessage / alternatives / hint shape | | vibe://error-code-catalog | Catalog of V1 API error codes and their response shapes |

Prompts

| Name | Description | |------|-------------| | create-bitrix24-app | Tool-first flow for creating, publishing, and deploying a Bitrix24 app. Covers handlerUrl vs appUrl split, IM iconName requirement, tariff-gate 402 handling | | deploy-app-step-by-step | Wake → upload → exec → healthcheck, with debug: true diagnostic call-out | | diagnose-server-issue | get_server → metrics → logs → repair hints | | upgrade-from-trial | Trial / tariff-gate explainer with upgrade alternatives |

API Key Types

• App key (vibe_app_...) — for entity CRUD, search, batch, aggregation, and app management
• Management key (vibe_live_...) — for portal and key management

Get your API key at vibecode.bitrix24.tech.

License

MIT