@bitrix24/mcp-vibecode-api

MCP (Model Context Protocol) server for Bitrix24 via the Vibe API. Gives AI assistants 67 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 |

Tools (67)

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 49 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, 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 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 | Revert an app to draft status | | 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. Enforces IM placements (IM_SIDEBAR, IM_NAVIGATION, IM_TEXTAREA) require options.iconName client-side — the B24 error is opaque |

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, list_deployments, exec, upload, logs. Supports debug: true and cleanDeploy | | 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 short-lived api-bearer JWTs + share-url shortcodes (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 | | manage_bot_messages | Message ops: send, edit, delete, add_reaction, remove_reaction, read (needs dialogId). For history use manage_chat (GET /v1/chats/:dialogId/messages) |

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, mirrors into resolution, emails the submitter on a real status change). 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 (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 |

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: presigned PUT URL for 10 MB–100 MB files (optional ttlSeconds, 60–86400) | | vibe_storage_complete_upload | Path B step 2: finalize a presigned upload | | vibe_storage_create_multipart | Path C: start a multipart upload for >100 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: 302-redirect download URL (10-min TTL, 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 | Web search via the configured provider(s); provider/credential render as dropdowns when the startup catalog is available | | web_research | Multi-step web research with streaming progress notifications |

Supported Entities (49)

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-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, 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 Bitrix24 and key management

Get your API key from your VibeCode.

License

MIT