@bitrix24/mcp-vibecode-api

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

Quick start

Point the server at your VibeCode with --api-url, using the API key you minted there.

ℹ️ The URL and key in the snippet below are an example — replace https://vibecode.bitrix24.com with your VibeCode URL and vibe_app_xxx_yyy_zz with a real API key.

npx @bitrix24/mcp-vibecode-api --key vibe_app_xxx_yyy_zz --api-url https://vibecode.bitrix24.com

⚠️ API keys are issued per VibeCode and are not portable. A key minted on one VibeCode will not work against another — always pass --api-url matching the one where you created the key. If you omit --api-url, the CLI prints a warning and falls back to a built-in default for backwards compatibility, so pass it explicitly to be sure.

MCP Client Configuration

Add the server to your MCP client's configuration (the mcpServers block). Always include --api-url matching where you minted the key:

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

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 — set to your VibeCode | | VIBE_MCP_HTTP_TOKEN | --http-token | Bearer token required by the HTTP transport | | VIBE_MCP_HTTP_TIMEOUT_MS | — | Outbound HTTP headers/idle timeout, ms (default 690000 — above the platform's 660 s window; long calls like deploy legitimately hold the connection for minutes while a sleeping host wakes) | | VIBE_MCP_USE_GLOBAL_FETCH | — | Set to 1 to route all platform calls through globalThis.fetch (for hosts whose APM instruments the global fetch). Disables the long-haul timeouts above — the global fetch's own limits apply |

Tools (69)

Plus check_for_updates (always registered) and, in degraded mode only, check_api_key.

Entity Tools (10)

| Tool | Description | |------|-------------| | discover | Get API schema — summary of all 50 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 |

Bitrix24 Tools (1)

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

Me Tools (1)

| Tool | Description | |------|-------------| | get_me | Caller identity, tariff, capabilities. sections narrows the response client-side and accepts only portal / tariff / capabilities / scopes — there is no trial section, and the access verdict lives in capabilities.servers.create. Supports 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 Bitrix24 | | 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 (9)

| Tool | Description | |------|-------------| | list_apps | List apps in the Bitrix24 ({ data, total, page, limit }; page/limit paginate, cap 200) | | get_app | Get a specific app by ID | | create_app | Create a new Bitrix24 OAuth app (handlerUrl is platform-set; configure appUrl for your placement iframe; mode sets READONLY/READWRITE) | | update_app | Update an existing app (title/description/appUrl/scopes/redirectUris/placements) | | delete_app | Delete an app permanently | | publish_app | Publish to the Bitrix24 catalog and bind placements (409 SNAPSHOT_REQUIRED only when source-storage is enabled; free-tariff placement.bind surfaces as 502 BITRIX_UNAVAILABLE) | | unpublish_app | Unpublish an app — removes it from the portal catalog (status UNPUBLISHED) | | save_sources | Push the app source tree to the backend (deterministic tar.gz snapshot) | | load_sources | Pull the app source tree back from the backend |

Placement Tools (1)

| Tool | Description | |------|-------------| | manage_placements | list_bound / list_available / bind / unbind. IM placements (IM_SIDEBAR, IM_NAVIGATION, IM_TEXTAREA) take an optional options.iconName — the server fills a default and echoes it in data.optionsDefaulted; no client-side pre-check |

Deployment Tools (1)

There is no backend "deployment" resource — catalog publishing is a single app-level toggle. deploy_app (PORTAL) maps to publish; its inverse is unpublish_app (App Tools). The former list_deployments / undeploy_app tools pointed at non-existent routes and were removed.

| Tool | Description | |------|-------------| | deploy_app | Publish an app to the PORTAL catalog (MARKETPLACE returns a structured 501 — not yet wired). For BH-server source deploy, use manage_server_deploy |

Infra Tools (5)

| 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, rename, set_access_policy, list_runtimes | | manage_server_deploy | Deploy pipeline: deploy, exec, upload, logs, clear_lock. Supports debug: true and cleanDeploy. Responses are synchronous JSON; literal query.stream="true" for exec/deploy is removed before the call and object responses receive a static _note. There is no deploy-history action — the backend does not persist deploy history | | manage_server_access | Black Hole access whitelist: list_access, add_access (department adds need departmentName), remove_access, b24_users_search (autocomplete) | | manage_server_tokens | BH access-tokens: mint / list / revoke / refresh short-lived api-bearer JWTs + share-url shortcodes. refresh re-mints the JWT of an existing token without spending the active-token cap or the mint limit (503 FEATURE_DISABLED when off) | | manage_server_events | OAuth-app server B24 event-subscriptions: list / add / remove |

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. After create, reuse the top-level chatId ("chatN") for every later action — chat.id and recentConfig.chatId are numeric and address a personal dialog | | manage_bot_messages | Message ops: send, edit, delete, add_reaction, remove_reaction, read, send_typing. send and read require top-level dialogId; for send, top-level is canonical and legacy body.dialogId remains a fallback. For history use manage_chat (GET /v1/chats/:dialogId/messages). dialogId takes "chatN" for a group chat; a bare number is a user ID and delivers to that user's personal dialog |

AI Credential Tools (1)

| Tool | Description | |------|-------------| | manage_ai_credentials | USER-scope BYOK: list, create, update, delete, test, usage, list_providers, plus credential-bound model management (fetch_models / list_models / add_model / delete_model for custom-openai-compat 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 / upload_attachment. Three access tiers (APP key / vibe:feedback scope / management key). Prefer comment over update for user-visible replies (posts a thread row, emails the submitter on a real status change; fills resolution only when the comment closes the ticket). WITHDRAWN is the author-only self-withdraw. Attach screenshots two-phase: upload_attachment → pass the returned id in attachmentIds. Never flip status to RESOLVED before the fix is deployed |

API Surface Tools (17)

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

| Tool | Description | |------|-------------| | ai_chat | Synchronous JSON chat completions via /v1/chat/completions; the dedicated tool does not expose an SSE flag | | manage_workday | Work-day start/stop, breaks, status queries, history records | | 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_catalog_product_image | List native catalog-product images (DETAIL_PICTURE, PREVIEW_PICTURE, MORE_PHOTO) or get one by ID; other custom File properties are excluded, and allowlisted DTOs omit signed/private download fields. Access to the untrusted detailUrl without a portal session is not guaranteed; never fetch it server-side without the platform SSRF policy | | manage_deal_products | Manage one deal's product rows: list, replace all, add, get/update/delete one row, or inspect product-row fields. Validates deal/row IDs and action-specific bodies before dispatch | | manage_post | Sonet post create/update/delete | | manage_userfield | Custom-field CRUD for CRM types, employees (entity: "users", UF_USR_ prefix, user.userfield scope) 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). create returns the numeric chat id in data; dialog-taking actions (get, send_message, read_messages) need "chatN", while add_users needs that bare number — a bare number in a dialog-taking action silently addresses that user's personal dialog | | crm_extras | Lead-convert, product-rows, and other CRM helpers | | manage_file | File upload/download via /v1/files | | call_api | Escape hatch for JSON V1 API calls when no typed tool exists. Unchanged JSON-only apiRequest never parses SSE: POST /v1/research is refused locally with NON_JSON_RESPONSE_UNSUPPORTED before HTTP (use web_research; do not retry); only boolean body.stream === true is cloned to false for POST search and both chat aliases; and stream is removed for POST exec/deploy only when the final normalized URL has exactly one value equal to literal true, preserving all other query pairs, order, and encoding. Each downgrade sends one JSON request and adds a static _note after spreading a non-null, non-array object, replacing any platform _note; null, arrays, and scalars are unchanged. Prefer web_research, web_search, ai_chat, and manage_server_deploy; known terminal binary/text routes remain locally rejected |

Storage Tools (11)

Object/file storage on /v1/storage/* (all require the vibe:storage scope). The owning app is derived from the API key's credential binding — appId is ignored (Phase 2b).

| Tool | Description | |------|-------------| | vibe_storage_upload | Path A: upload a small file (<10 MB) directly via the backend (base64 on the wire) | | vibe_storage_create_upload_url | Path B — TEMPORARILY DISABLED, answers 503 STORAGE_PRESIGNED_UPLOAD_DISABLED; use vibe_storage_create_multipart instead | | vibe_storage_complete_upload | Path B step 2 — TEMPORARILY DISABLED, answers 503 STORAGE_PRESIGNED_UPLOAD_DISABLED | | vibe_storage_create_multipart | Path C: start a multipart upload for anything over 10 MB (up to 5 TB), parallel + resumable | | vibe_storage_complete_multipart | Path C: finalize with the collected parts[] | | vibe_storage_abort_multipart | Path C: cancel an in-flight multipart upload | | vibe_storage_get_url | Read: returns { url } with the presigned download URL itself — the tool does not follow the redirect and does not download the object, so binary content works too (URL valid ~10 min, rotates per call) | | vibe_storage_delete | Soft-delete an object (30-day grace) | | vibe_storage_get_usage | Self-monitor: storage usage for the caller | | vibe_storage_list | List objects (cursor pagination, prefix filter) | | vibe_storage_get_public_url | Form the anonymous /v1/public-storage/{portalId}/{objectId} link (needs the Bitrix24's publicGetEnabled) |

Web Tools (2)

| Tool | Description | |------|-------------| | web_search | Synchronous JSON web search via the configured provider(s); it fixes stream:false, and provider/credential render as dropdowns when the startup catalog is available | | web_research | Multi-step web research with streaming progress notifications |

Supported Entities (50)

deals, contacts, companies, leads, quotes, activities, products, product-sections, statuses, currencies, deal-categories, categories, requisites, requisite-presets, bank-details, timelines, invoices, items, smart-processes, tasks, calendar-events, calendar-sections, files, folders, storages, users, departments, workgroups, humanresources-nodes, mail-mailboxes, list-elements, catalogs, catalog-products, catalog-services, catalog-skus, catalog-offers, 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.

Not every entity supports every operation — some disable specific generic ops on the backend (e.g. list-elements has no generic CRUD, mail-mailboxes is read-only). Call discover { entity } for the per-entity operation list. addresses (composite key) and task-comments (nested) are reachable via call_api. chats / messages are not generic entities — use manage_chat / manage_bot_chat / manage_bot_messages.

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 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 49 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, the optional IM iconName and its server default, 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 Bitrix24 and key management

Get your API key from your VibeCode.

License

MIT