Bitrix MCP

Русская документация

Bitrix MCP is a local, token-free MCP server for AI assistants that work with Bitrix Framework / 1C-Bitrix projects. It indexes your project, templates, Bitrix modules, install assets, and documentation so an AI agent can search real project symbols and docs without installing a Bitrix module or changing the runtime.

Who this is for

Use Bitrix MCP when you want an MCP-capable assistant such as Cursor, Claude Desktop, Claude Code, PhpStorm / JetBrains AI Assistant, VS Code / GitHub Copilot, Windsurf, Cline, Roo Code, Continue, Gemini CLI, OpenAI Codex, or Kilo Code to answer questions about a local Bitrix project, find framework APIs, inspect event handlers, or work with templates using indexed local context.

Capabilities

• LiveAPI search: indexes PHP sources from an installed Bitrix instance and searches functions, classes, methods, events, components, constants, and Bitrix module include/check usage records.
• Project indexing: indexes the current project from a terminal command or MCP tool.
• Template indexing: separately indexes templates, components, scripts, styles, and layout assets.
• Documentation search: exposes local Bitrix Framework documentation as MCP resources and searches indexed Markdown/text docs with SQLite FTS.
• Optional semantic documentation search: delegates embedding search to a Python sentence-transformers FastAPI service when explicitly enabled.
• Bitrix dependency graph: queries bitrix_relations as a Bitrix-aware graph of events, handlers, modules, agents, mail events, ORM entities, components, templates, iblocks, hlblocks, options, and inheritance.
• Local access model: no token or Bitrix authentication is required; access is controlled by where you run the process and which local folders you expose.

System requirements

• Operating system: Linux, macOS, or Windows / Windows PowerShell.
• Node.js 22.12+ because Bitrix MCP uses node:sqlite.
• npm 10+.
• Disk access to the Bitrix project you want to index.
• Network access is recommended for the first documentation index because the official Bitrix Framework docs repository is cloned or updated by default.
• Python 3.11+ is required only for optional semantic documentation search.

The server uses @modelcontextprotocol/sdk v1.29.0.

Dependencies

Runtime dependencies are installed by npm install and include:

• @modelcontextprotocol/sdk — MCP server protocol support.
• fast-glob, ignore — file discovery and ignore handling.
• php-parser — PHP symbol parsing for Bitrix and project sources.
• zod — schema validation.

Optional semantic search dependencies live in embeddings/requirements.txt and are installed only if you run the Python embeddings service.

Installation from npm

Install globally:

npm install -g @mb4it/bitrix-mcp

Or run without a global install:

npx @mb4it/bitrix-mcp init --agent cursor --no-serve

The installed CLI command remains bitrix-mcp:

bitrix-mcp --help
bitrix-mcp init --agent cursor --no-serve
bitrix-mcp index-all
bitrix-mcp serve

MCP result authority

Bitrix MCP provides deep, specialized indexing of the Bitrix Framework and your project code. When using an AI assistant with Bitrix MCP:

• Primary Source of Truth: Treat MCP tool results as authoritative for project symbols, framework APIs, event handlers, ORM entities, and documentation.
• Manual Search as Fallback: AI agents are instructed to search files manually or use `grep` only when MCP tools return no results, indicate a stale index, or when you explicitly ask for a manual check.
• Authority Rule: Successful, non-empty MCP results should not be contradicted by unindexed manual assumptions.

This behavior reduces token waste and prevents the assistant from hallucinating based on incomplete manual file scans.

Quick start

From the root of your Bitrix project:

# 1. Install the package dependencies if you use a local checkout of this repo
npm install
npm run build

# 2. Go to the Bitrix project you want to index
cd /path/to/bitrix/project

# 3. Configure your MCP client and create .bitrix-mcp indexes
# In CI or scripts, --no-serve avoids taking over stdio after setup.
npx @mb4it/bitrix-mcp init --agent cursor --no-serve

During interactive init, select one or more AI agents from the prompt. For non-interactive setup, pass --agent <id> (repeat or comma-separate IDs), --all-agents, or --yes for the default Cursor setup. Bitrix MCP writes or updates the selected agents' MCP configuration, creates reusable guidance/rule files (and installs the skill into .claude/skills/ for Claude agents), and builds initial indexes. init does not start the stdio server itself — the MCP config it writes launches bitrix-mcp serve from your client, so the client starts the server. Pass --serve to start it immediately, or run bitrix-mcp serve manually.

After setup, open your AI client and ask it to use Bitrix MCP. A good first prompt is:

Use Bitrix MCP to check index status, then find how this project registers sale module event handlers.

If you only need to run or refresh indexes manually:

# Index everything: project, templates, Bitrix modules, install assets, and docs
npx @mb4it/bitrix-mcp index-all

# Show index counters, resolved runtime paths, and diagnostics
npx @mb4it/bitrix-mcp status
npx @mb4it/bitrix-mcp config
npx @mb4it/bitrix-mcp doctor

# Start the MCP server after indexes already exist
npx @mb4it/bitrix-mcp serve

Common workflows

| Goal | Command | What it changes | When to use | | --- | --- | --- | --- | | Configure one MCP client and build initial indexes without occupying stdio | npx bitrix-mcp init --agent cursor --no-serve | Updates the selected client MCP config and guidance/rule files, creates .bitrix-mcp/, indexes missing project/template/Bitrix code scopes, and indexes docs. | Recommended first setup for scripts, CI-like shells, or any terminal where you do not want init to stay attached as an MCP server. | | Configure only client files and guidance | npx bitrix-mcp configure --agent cursor | Updates MCP config and guidance/rule files only; does not build indexes and does not start the server. | Use when indexes already exist or another process will run indexing separately. | | Refresh every index with official docs | npx bitrix-mcp index-all | Rebuilds/updates project, template, Bitrix module, install asset, and documentation indexes in .bitrix-mcp/; official docs are auto-registered/updated by default. | Use after larger codebase changes, dependency/module updates, or when docs search should include the official Bitrix Framework docs repository. | | Fast path without official docs | BITRIX_MCP_OFFICIAL_DOCS_ENABLED=0 bitrix-mcp index-all | Rebuilds/updates all code indexes and indexes only local/explicit documentation sources; skips cloning or pulling the official docs repository. | Use in offline environments, first-run demos, CI jobs without network access, or whenever local docs are enough. | | Refresh code only | npx bitrix-mcp index-code | Rebuilds/updates project, template, Bitrix module, and install asset indexes; leaves documentation unchanged. | Use after PHP/template/module changes when documentation was not changed. | | Verify configuration and health | npx bitrix-mcp doctor --verbose | Does not modify project files; creates/opens the SQLite DB if needed and prints health checks plus resolved runtime config. | Use when an MCP client cannot find indexes/docs, when paths look wrong, or after changing environment variables. |

The fast no-official-docs path is intentionally a single-command override:

BITRIX_MCP_OFFICIAL_DOCS_ENABLED=0 bitrix-mcp index-all

Use the same environment variable with npx if the package is not installed globally: BITRIX_MCP_OFFICIAL_DOCS_ENABLED=0 npx bitrix-mcp index-all.

CLI usage

# Configure an agent, create .bitrix-mcp indexes, and start stdio server
npx @mb4it/bitrix-mcp init

# Non-interactive init for scripts/CI: configure Cursor, skip serving after setup
npx @mb4it/bitrix-mcp init --agent cursor --no-serve

# Configure MCP config and guidance only; do not index or start the server
npx @mb4it/bitrix-mcp configure --agent cursor

# Start MCP server over stdio for Cursor, PhpStorm, Claude Desktop, Kilo, etc.
npx @mb4it/bitrix-mcp serve

# Index everything: project, templates, Bitrix modules, install assets, and docs
npx @mb4it/bitrix-mcp index-all

# Index all code scopes without documentation
npx @mb4it/bitrix-mcp index-code

# Index the current project
npx @mb4it/bitrix-mcp index-project /path/to/project

# Index templates/components/scripts/styles separately
npx @mb4it/bitrix-mcp index-template /path/to/project

# Index installed Bitrix Framework PHP sources for LiveAPI
cd /path/to/bitrix/project
npx @mb4it/bitrix-mcp index-bitrix

# Index Bitrix module install assets
npx @mb4it/bitrix-mcp index-install /path/to/project

# Register, update, and index documentation sources
npx @mb4it/bitrix-mcp docs-add-git https://github.com/bitrix-tools/framework-docs.git
npx @mb4it/bitrix-mcp docs-add-path /path/to/local/docs
npx @mb4it/bitrix-mcp docs-update
npx @mb4it/bitrix-mcp index-docs

# Send SQLite documentation chunks to the embeddings service
npx @mb4it/bitrix-mcp index-embeddings
# Or reindex SQLite docs and embeddings together when the service is running
npx @mb4it/bitrix-mcp index-docs --embeddings

# Search indexed Bitrix module include/check API usages by module
npx @mb4it/bitrix-mcp search-modules iblock

# Query the Bitrix-aware dependency graph
npx @mb4it/bitrix-mcp graph-neighbors event main:OnBeforeProlog --direction both
npx @mb4it/bitrix-mcp impact-radius local/php_interface/init.php --depth 2

# Show index counters, resolved runtime paths, or environment diagnostics
npx @mb4it/bitrix-mcp status
npx @mb4it/bitrix-mcp config
npx @mb4it/bitrix-mcp doctor

Generated indexes are written to .bitrix-mcp/ by default. Indexing always applies built-in ignores for heavy/generated directories such as node_modules/, vendor/, .git/, dist/, build/, upload/, cache/, and generated/; it also reads project .gitignore rules when present.

To exclude additional project-specific files from LiveAPI and template indexes, add a .bitrixmcpignore file to the project root. It uses the same pattern syntax as .gitignore and is applied together with the built-in rules and .gitignore:

# Generated local scripts
local/scripts/generated/**

# Private custom code that should not be searchable
private/*.php
assets/ignored.js

Bitrix core indexing

The Bitrix core (/bitrix/) is large, so indexing is curated and controllable.

What the bitrix scope indexes (command index-bitrix, and the Bitrix part of index-code / index-all):

• bitrix/modules/**/*.php — module PHP (classes, ORM, events, API usages)
• bitrix/admin/**/*.php and bitrix/tools/**/*.php
• bitrix/js/** and local/js/** — core JS (frontend ↔ logic bindings)
• local/modules/**/*.php — your custom modules

Excluded by default (always, even with --full for the runtime/static ones):

• runtime/cache/generated: bitrix/cache, managed_cache, html_pages, upload, …
• static assets: bitrix/images, themes, fonts, panel, …
• bitrix/wizards/**
• module install/** (install assets are their own index-install scope)
• lang/** message files — excluded across all scopes (modules, components, templates, project), not just here (re-enable with --include-lang / --full)

Components and templates are indexed by the template scope (bitrix/components, bitrix/templates, and the local/ equivalents), which runs in index-template, index-code and index-all.

The project scope (index-project) indexes your project's own code only and never crawls /bitrix/ — the core is owned by the dedicated bitrix scope above.

Common workflows

# Index the whole core (all modules, no lang). This is the default.
npx @mb4it/bitrix-mcp index-bitrix

# Index only specific modules (much faster on a real project)
npx @mb4it/bitrix-mcp index-bitrix --modules=main,iblock

# Online store
npx @mb4it/bitrix-mcp index-bitrix --modules=main,iblock,sale,catalog,currency

# Full index: every module + lang files (slow; prints a warning)
npx @mb4it/bitrix-mcp index-bitrix --full

# Dry run: show what would be indexed (found / ignored / queued, top modules)
npx @mb4it/bitrix-mcp index-bitrix --plan --modules=main,iblock

# index-code / index-all: skip the core, or narrow it
npx @mb4it/bitrix-mcp index-all --no-bitrix
npx @mb4it/bitrix-mcp index-all --bitrix-modules=main,iblock

Flags

| Flag | Applies to | Effect | | --- | --- | --- | | --modules=main,iblock | index-bitrix | Index only these core modules (default: all). --modules=all for every module. | | --bitrix-modules=… | index-code, index-all | Same selection for the Bitrix part of those commands. | | --full | index-bitrix, index-code, index-all | Every module plus lang/ and install assets. Alias for --modules=all --include-lang --install. Prints a slow-run warning. | | --include-lang | all Bitrix index commands | Include lang/ message files (off by default in every scope). | | --install | index-code, index-all | Also index module install/ assets (off by default — install is its own index-install scope). | | --no-bitrix | index-code, index-all | Skip the Bitrix core and install scopes entirely. | | --plan | index-bitrix | Print the indexing plan (files found / ignored / queued, top modules) and exit without indexing. |

Unknown module names print a warning (e.g. module "foo" was requested but not found) and are skipped; the run continues as long as at least one requested module exists.

Incremental reindex

Reindexing is incremental: a file is re-parsed only when its size or mtime changed since the last run. Unchanged files are skipped and stay in the index; deleted files are removed. So the first index-bitrix is the slow one — subsequent runs are fast. The progress summary reports indexed vs skipped counts (see below).

.bitrixmcpignore rules are applied on top of these built-in rules.

Indexing progress

Indexing a full Bitrix project (especially index-bitrix over a real /bitrix/ tree) can take many minutes. To make the process visible, every index-* command shows progress while it works.

# Default: live progress in an interactive terminal
npx @mb4it/bitrix-mcp index-project
npx @mb4it/bitrix-mcp index-bitrix

# Compact progress: dots for work, checkmarks for completed phases/scopes
npx @mb4it/bitrix-mcp index-bitrix --compact

# Disable progress entirely
npx @mb4it/bitrix-mcp index-all --no-progress

# Force progress on a non-interactive shell (e.g. when piping to a log)
npx @mb4it/bitrix-mcp index-bitrix --progress

# Machine-readable JSON Lines progress (to stderr)
npx @mb4it/bitrix-mcp index-bitrix --json-progress

Behaviour:

• Progress is on by default in an interactive terminal (stderr is a TTY).

• --compact prints a short line per scope with . for ongoing work and ✓ for completed phases, followed by a one-line summary per scope. Example for index-all:

  project    ✓ . ✓ ✓ ✓
  ✓ project indexed in 00:03 | files: 412 | skipped: 0 | symbols: 1 980 | relations: 220
  template   ✓ . . ✓ ✓ ✓
  ✓ template indexed in 00:02 | files: 168 | skipped: 0 | symbols: 540 | relations: 12
  bitrix     ✓ . . . . . . . ✓ ✓ ✓
  ✓ bitrix indexed in 07:43 | files: 16 811 | skipped: 0 | symbols: 38 210 | relations: 4 712
  docs       ✓
  ✓ docs indexed | docs: 1 240
  all        ✓
  ✓ all indexed in 08:31 | files: 17 391 | docs: 1 240

• --no-progress disables progress output completely.

• --json-progress emits one JSON object per event ({"phase":"parse","scope":"bitrix","current":1200,"total":16811,...}).

• Progress is always written to stderr, never stdout, so it never interferes with the MCP stdio (serve) JSON-RPC protocol or with piped command output.

• In CI / non-interactive environments progress is off by default; pass --progress, --compact, or --json-progress to force it on.

• If NO_COLOR is set (or the terminal lacks unicode), the reporters fall back to ASCII marks.

Bitrix dependency graph and impact radius

Bitrix MCP builds a queryable graph from indexed bitrix_relations rather than a generic AST dependency graph. Each edge is a Bitrix relation in the form source_type:source_name --relation_type--> target_type:target_name, for example:

• event:main:OnBeforeProlog --handles_event--> method:Vendor\Module\Handler::onBeforeProlog
• file:local/php_interface/init.php --registers_event_handler--> event:main:OnBeforeProlog
• component:bitrix:catalog.section --uses_iblock--> iblock:CATALOG_IBLOCK_ID
• orm_entity:Vendor\Module\ProductTable --references_orm_entity--> orm_entity:Bitrix\Main\UserTable

This graph differs from a code-review AST graph because it follows Bitrix concepts that are often dynamic or configured through framework APIs: events and event handlers, module includes, agents, mail events, ORM entity references, components/templates, iblock and highloadblock usage, options, assets, and PHP inheritance relations.

MCP tools:

• bitrix_graph_neighbors returns direct or bounded-depth neighbors for a node. Parameters include nodeType, nodeName, direction (out, in, both), relationType, depth, limit, and format.
• bitrix_graph_traverse performs safe BFS traversal with cycle protection. Parameters include startType, startName, direction, maxDepth, relationTypes, limit, and format.
• bitrix_impact_radius starts from provided files or git diff --name-only <base> (default HEAD~1) and groups impacted events, handlers, components, templates, ORM entities, agents, mail events, iblocks, hlblocks, modules, options, classes, and methods. It can include relation-weighted risk reasons for high-impact relations such as handles_event, registers_event_handler, registers_agent, sends_mail_event, references_orm_entity, includes_component, uses_template, extends, and implements.

Examples:

bitrix_graph_neighbors({
  "nodeType": "event",
  "nodeName": "main:OnBeforeProlog",
  "direction": "both"
})

bitrix_graph_traverse({
  "startType": "component",
  "startName": "bitrix:catalog.section",
  "maxDepth": 2,
  "relationTypes": ["uses_iblock", "uses_template"]
})

bitrix_impact_radius({
  "files": ["local/php_interface/init.php"],
  "maxDepth": 2,
  "includeRisk": true
})

Optional CLI equivalents are available for quick inspection:

npx @mb4it/bitrix-mcp graph-neighbors event main:OnBeforeProlog --direction both
npx @mb4it/bitrix-mcp impact-radius local/php_interface/init.php --depth 2

Configuration

Override paths and optional features with environment variables:

• BITRIX_MCP_DATA_DIR — index storage directory.
• BITRIX_MCP_WORKSPACE — project root used by the MCP server.
• BITRIX_MCP_DOCS_PATHS — documentation directories separated by the platform path delimiter (: on Unix, ; on Windows).
• BITRIX_MCP_DOCS_DIR — legacy single documentation directory exposed as MCP resources.
• BITRIX_ROOT — default Bitrix project root for index-bitrix, index-code, and index-all.
• BITRIX_MCP_EMBEDDINGS_URL — Python embeddings service URL, default http://127.0.0.1:8765.
• BITRIX_MCP_SEMANTIC_ENABLED — enables the optional bitrix_semantic_docs_search MCP tool when set to 1, true, yes, or on; disabled by default.
• BITRIX_MCP_OFFICIAL_DOCS_ENABLED — automatically registers, clones or pulls, and indexes the official Bitrix Framework documentation repository during index-docs, index-all, and bitrix_index_docs; enabled by default, set to 0 to use only explicitly registered/local docs.

Documentation search modes

Bitrix MCP supports two documentation search modes:

1. Local SQLite FTS (default) — run bitrix-mcp index-docs, bitrix-mcp index-all, or the MCP tool bitrix_index_docs to clone/pull the official Bitrix Framework documentation repository, index registered Markdown/text documentation into .bitrix-mcp/bitrix-mcp.sqlite, and search it with bitrix_docs_search. This mode does not need Python or the embeddings service; it needs network access only when cloning or pulling Git documentation sources.
2. Semantic embeddings (optional) — first run bitrix-mcp index-docs so SQLite contains the canonical documentation chunks, start the Python FastAPI service from embeddings/, run bitrix-mcp index-embeddings (or bitrix-mcp index-docs --embeddings) to POST those same chunks to /index, and then set BITRIX_MCP_SEMANTIC_ENABLED=1 for the MCP server. This registers the additional bitrix_semantic_docs_search MCP tool, which calls BITRIX_MCP_EMBEDDINGS_URL.

Use local FTS as the baseline documentation search. Enable semantic mode only when you need embedding-based ranking and can run the Python service alongside the MCP server.

bitrix-mcp init

Run init from the root of a Bitrix project after installing @mb4it/bitrix-mcp globally or making bitrix-mcp available on your PATH:

cd /path/to/bitrix/project
bitrix-mcp init

The command uses the current working directory as the project root, creates <projectRoot>/.bitrix-mcp, sets BITRIX_MCP_WORKSPACE to <projectRoot>, BITRIX_MCP_DATA_DIR to <projectRoot>/.bitrix-mcp, and BITRIX_MCP_DOCS_DIR to <projectRoot>/docs. When <projectRoot>/bitrix exists, it also sets BITRIX_ROOT to <projectRoot>. It then asks which AI agents to configure. You can enter one number or multiple numbers separated by commas; each selected client gets its own MCP configuration created or updated:

• Cursor — .cursor/mcp.json.
• Claude Code — project .mcp.json (this is also what Claude Desktop reads per project).
• PhpStorm / JetBrains — prints a JetBrains AI Assistant MCP JSON snippet to paste into the IDE settings.
• VS Code / GitHub Copilot — .vscode/mcp.json using the VS Code servers format.
• Windsurf — ~/.codeium/windsurf/mcp_config.json.
• Cline — ~/.cline/data/settings/cline_mcp_settings.json.
• Roo Code — .roo/mcp.json.
• Continue — .continue/mcpServers/bitrix-mcp.json.
• Gemini CLI — .gemini/settings.json.
• OpenAI Codex — ~/.codex/config.toml.
• Kilo Code — ~/.kilocode/cli/global/settings/mcp_settings.json.
• Other MCP clients — a custom JSON path entered during setup.

For supported JSON clients, init reads the existing MCP config and adds or updates only the bitrix-mcp entry, preserving other MCP servers and unrelated settings. For every selected agent, init also creates a reusable Bitrix MCP skill at .bitrix-mcp/skills/bitrix-mcp/SKILL.md and writes an agent-specific rule file so the agent knows when to call the MCP tools:

• Cursor — managed body section in .cursor/rules/bitrix-mcp.mdc while preserving existing .mdc frontmatter.
• Claude Code — managed section in CLAUDE.md (plus the skill in .claude/skills/bitrix-mcp/SKILL.md).
• PhpStorm / JetBrains — managed section in .junie/guidelines.md.
• VS Code / GitHub Copilot — managed section in .github/copilot-instructions.md.
• Windsurf — managed section in .windsurf/rules/bitrix-mcp.md.
• Cline — managed section in .clinerules/bitrix-mcp.md.
• Roo Code — managed section in .roo/rules/bitrix-mcp.md.
• Continue — managed section in .continue/rules/bitrix-mcp.md.
• Gemini CLI — managed section in GEMINI.md.
• OpenAI Codex — managed section in AGENTS.md.
• Kilo Code — managed section in .kilocode/rules/bitrix-mcp.md.
• Other MCP clients — managed section in .bitrix-mcp/rules/bitrix-mcp.md.

Generated rule files are safe to update with repeated bitrix-mcp init runs: new files receive the full Bitrix MCP template, while existing Markdown and Cursor .mdc rule files preserve user content and replace only the bitrix-mcp:init-guidance managed section on reruns. The bitrix-mcp server runs:

{
  "command": "bitrix-mcp",
  "args": ["serve"]
}

init and configure flags

• --agent <id> — select agents without a prompt. Repeat it or use commas, for example --agent cursor,codex. Supported IDs are cursor, claude-code, jetbrains, vscode, windsurf, cline, roo-code, continue, gemini-cli, codex, kilo-code, and generic-json. (Claude Desktop reads the project .mcp.json, so use claude-code for it.)
• --all-agents — configure every built-in agent that does not need an extra custom path prompt.
• --yes / -y — accept the default non-interactive agent choice (cursor).
• --no-index — skip project/template/Bitrix code indexing during init.
• --no-docs — skip documentation indexing during init.
• --no-official-docs — index only local/registered documentation sources and do not clone or update the official Bitrix Framework docs during init.
• --serve — start the MCP stdio server after init (by default init does not — the MCP client launches bitrix-mcp serve itself).
• --no-serve — explicit no-op for the default behavior (kept for backward compatibility).

Use bitrix-mcp configure with the same agent-selection flags when you only want MCP configuration and guidance files. configure never indexes code/docs and never starts the server.

After writing the selected configurations, init creates .bitrix-mcp/, builds missing project/template indexes, builds a Bitrix core index when a local bitrix/ directory is detected, and clones or pulls and indexes documentation sources including the official Bitrix Framework docs repository. init does not start the MCP stdio server by default — the MCP config it writes launches bitrix-mcp serve from your client, so the client starts the server when it connects. Pass --serve to start the server immediately (e.g. for a manual smoke test), or run bitrix-mcp serve yourself.

MCP tools

• Index/status/config/doctor: bitrix_index_project, bitrix_index_template, bitrix_index_all, bitrix_index_docs, bitrix_index_status plus CLI config and doctor.
• LiveAPI and symbol search: bitrix_liveapi_search, bitrix_event_search, bitrix_module_usage_search, bitrix_inheritance_search.
• Source context: bitrix_read_file_context, bitrix_read_symbol_context.
• Agents and mail events: bitrix_agent_search, bitrix_mail_event_search.
• Components: bitrix_component_search, bitrix_component_context.
• ORM: bitrix_orm_search, bitrix_orm_entity_map, bitrix_orm_usage_search.
• IBlock / Highloadblock / Options: bitrix_iblock_usage_search, bitrix_hlblock_usage_search, bitrix_option_search.
• Relations and graph: bitrix_relation_search, bitrix_graph_neighbors, bitrix_graph_traverse, bitrix_impact_radius.
• Detect changes: bitrix_detect_changes combines Git-changed indexed records with graph impact, merged risk, and recommendations.
• Autoload and overview: bitrix_autoload_search, bitrix_project_overview.
• Docs search and API explanation: bitrix_docs_search, bitrix_docs_for_symbol, bitrix_explain_api_usage, and optional bitrix_semantic_docs_search when BITRIX_MCP_SEMANTIC_ENABLED is enabled.
• Benchmarks: CLI benchmark writes .bitrix-mcp/benchmark.json and .bitrix-mcp/benchmark.md.

Search result formats

Search tools support shared response-shaping options:

• kind: for bitrix_liveapi_search, bitrix_event_search, and bitrix_module_usage_search, restrict results to one index kind ("project", "template", "bitrix", or "install") or an array of kinds.
• preferLocal: for bitrix_liveapi_search and bitrix_event_search, boost project and template results ahead of equally relevant bitrix and install results; defaults to true.
• format: "compact" (default) or "full".
• includeSignature: include the compact signature field for symbol/event results; defaults to true.
• maxSignatureChars: truncate compact signatures to this many characters; defaults to 160.
• maxTextChars: truncate documentation excerpts to this many characters; defaults to 500.

Compact mode is optimized for agent context windows. bitrix_liveapi_search and bitrix_event_search return short rows with score, type, kind, name, module, workspace-relative file, line, and a truncated signature when available:

{
  "query": "CIBlockElement::GetList",
  "limit": 3
}

Example compact response shape:

[
  {
    "score": 1,
    "type": "method",
    "kind": "bitrix",
    "name": "CIBlockElement::GetList",
    "module": "iblock",
    "file": "bitrix/modules/iblock/classes/general/iblockelement.php",
    "line": 785,
    "signature": "CIBlockElement::GetList($arOrder = [], $arFilter = [], $arGroupBy = false, $arNavStartParams = false, $arSelectFields = [])"
  }
]

After a symbol search returns a file and line, call bitrix_read_file_context to inspect the surrounding implementation without exposing paths outside the configured workspace/data allowlist:

{
  "file": "bitrix/modules/iblock/classes/general/iblockelement.php",
  "line": 785,
  "before": 8,
  "after": 24,
  "maxChars": 12000
}

Example response shape:

{
  "metadata": {
    "absolutePath": "/path/to/project/bitrix/modules/iblock/classes/general/iblockelement.php",
    "relativePath": "bitrix/modules/iblock/classes/general/iblockelement.php",
    "language": "php",
    "startLine": 777,
    "endLine": 809,
    "totalLines": 4230,
    "truncated": false
  },
  "numberedLines": "777: ...\n785: public static function GetList(...)\n809: ..."
}

Module usage compact mode returns the module name, API call, index kind, relative file, line, and exact call signature:

{
  "module": "iblock",
  "limit": 5
}

Example compact module usage response shape:

[
  {
    "module": "iblock",
    "call": "Loader::includeModule",
    "kind": "project",
    "file": "local/php_interface/init.php",
    "line": 42,
    "signature": "Loader::includeModule('iblock')"
  }
]

Documentation search compact mode returns an excerpt instead of the full indexed chunk. Matching query terms are highlighted when possible; otherwise the chunk is truncated:

{
  "query": "sale order event",
  "limit": 2,
  "maxTextChars": 300
}

Example compact documentation response shape:

[
  {
    "score": 0.9,
    "type": "doc",
    "title": "Sale events",
    "uri": "bitrix-docs://framework/sale/events.md",
    "path": "sale/events.md",
    "chunkIndex": 0,
    "excerpt": "...register handlers for **sale** **order** **event** callbacks..."
  }
]

Use full mode when you need the raw indexed payload, including full symbol metadata or full documentation chunk text:

{
  "query": "CIBlockElement::GetList",
  "limit": 1,
  "format": "full"
}

To reduce symbol/event output further while staying in compact mode, disable signatures explicitly:

{
  "query": "OnSaleOrderSaved",
  "format": "compact",
  "includeSignature": false
}

Search by index kind

Use kind when you want to separate local project code from Bitrix core, templates, or module install assets. If kind is omitted, project and template matches are boosted ahead of equally relevant core/install matches by default.

Search only project event handlers:

{
  "query": "OnBeforeProlog",
  "module": "main",
  "kind": "project",
  "limit": 10
}

Search only Bitrix core API symbols:

{
  "query": "CIBlockElement::GetList",
  "type": "method",
  "kind": "bitrix",
  "limit": 5
}

Search only module install assets, for example frontend exports or admin widgets indexed from install/js:

{
  "query": "VendorWidget",
  "kind": "install",
  "limit": 10
}

You can also pass an array to search several source kinds while still excluding the rest, for example { "kind": ["project", "template"] }.

MCP resources

• bitrix-docs://index — JSON list of local documentation resources.
• bitrix-docs://framework/getting-started.md — bundled starter reference.

By default documentation indexing uses https://github.com/bitrix-tools/framework-docs.git plus any local docs/ directory and registered docs sources. Place additional .md or .txt files under docs/ to expose them through the documentation index, or set BITRIX_MCP_OFFICIAL_DOCS_ENABLED=0 to skip the official repository.

Example prompts

Use prompts like these in your MCP-capable AI client after Bitrix MCP is configured:

Use Bitrix MCP to show index status and tell me whether project, template, Bitrix, and documentation indexes are ready.

Use bitrix_liveapi_search to find examples of CIBlockElement::GetList usage and explain the parameters relevant to this project.

Search Bitrix MCP docs for sale order event handlers, then find matching handlers in this project.

Use Bitrix MCP to inspect local/templates/main and explain which components and template assets are used on the catalog page.

Before changing code, use Bitrix MCP to find existing project helpers for user fields and suggest the safest implementation plan.

Refresh Bitrix MCP indexes, then check whether any custom module install assets define admin JavaScript widgets.

Python embeddings service

cd embeddings
python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
# .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn service:app --host 127.0.0.1 --port 8765

Recommended semantic indexing sequence:

# 1. Populate SQLite with documentation chunks.
bitrix-mcp index-docs

# 2. Start the embeddings service in another shell.
cd embeddings
uvicorn service:app --host 127.0.0.1 --port 8765

# 3. Send the SQLite chunks to the embeddings service.
bitrix-mcp index-embeddings
# Or combine steps 1 and 3 when the service is already running:
bitrix-mcp index-docs --embeddings

# 4. Enable the semantic MCP tool before starting the MCP server.
export BITRIX_MCP_SEMANTIC_ENABLED=1
bitrix-mcp serve

bitrix-mcp doctor checks the embeddings service health only when semantic mode is enabled with BITRIX_MCP_SEMANTIC_ENABLED=1; otherwise it reports that semantic search is disabled and skips the embeddings request. When enabled, it also verifies that the service document count matches the current SQLite documentation chunk count. If the counts differ, rerun bitrix-mcp index-embeddings after bitrix-mcp index-docs.

Troubleshooting runtime configuration

Use bitrix-mcp config when an MCP client starts the server from a different directory than expected, writes indexes to an unexpected location, or cannot find documentation/Bitrix sources. The command prints the exact values resolved by resolveRuntimePaths: workspaceRoot, dataDir, sqlitePath, docsPaths, bitrixRoot, embeddingsUrl, semanticEnabled, and officialDocsEnabled. It also reports whether common MCP client config files are present for Cursor, Claude Code, VS Code/GitHub Copilot, Windsurf, Cline, Roo Code, Continue, Gemini CLI, OpenAI Codex, and Kilo Code.

bitrix-mcp config
bitrix-mcp config --json

For a combined health check and configuration dump, run bitrix-mcp doctor --verbose. Scripts and CI jobs can use JSON output from bitrix-mcp doctor --json; the process still exits with a non-zero status when doctor detects an error.

bitrix-mcp doctor --verbose
bitrix-mcp doctor --json

Common doctor warnings and fixes:

| Warning | What it usually means | What to do | | --- | --- | --- | | WARNING bitrixRoot: Bitrix root was not detected | The current workspace does not contain ./bitrix, and BITRIX_ROOT is not set. Code indexing still works for project/templates, but LiveAPI core indexing is skipped. | Run commands from the Bitrix project root, pass a root to index-bitrix, or export BITRIX_ROOT=/path/to/bitrix/project. | | WARNING bitrixRoot: BITRIX_ROOT is set ... but .../bitrix is missing | BITRIX_ROOT points to the wrong directory or to a checkout without the bitrix/ directory. | Fix BITRIX_ROOT and rerun bitrix-mcp doctor; then rerun bitrix-mcp index-bitrix or bitrix-mcp index-code. | | WARNING docsSources: No documentation paths or registered documentation sources found | No local docs path is configured and no docs source was registered in .bitrix-mcp/. | Add Markdown/text files under docs/, run bitrix-mcp docs-add-path /path/to/docs, or allow official docs with BITRIX_MCP_OFFICIAL_DOCS_ENABLED=1 bitrix-mcp index-docs. | | WARNING docsSources: Missing documentation source directories | A configured docs path or Git checkout directory no longer exists. | Restore the directory, update BITRIX_MCP_DOCS_PATHS, remove/re-add the docs source, or run bitrix-mcp docs-update for Git sources. | | WARNING bitrixmcpignore: .bitrixmcpignore is not present | This is only a reminder that Bitrix MCP will use built-in ignores and .gitignore rules. | Optional: create .bitrixmcpignore if you need to exclude private/generated files from Bitrix MCP indexes. | | WARNING phpParse: ... used regex fallback | Some PHP files could not be parsed by the AST parser, so Bitrix MCP indexed them with a regex fallback. | Reindex with BITRIX_MCP_DEBUG_PARSE=1 bitrix-mcp index-code to print file paths, then fix invalid PHP if needed. Existing fallback results are usually still searchable. | | WARNING embeddingsService: ... unavailable | Semantic search is enabled, but the Python embeddings service is not reachable. | Start the service from embeddings/, check BITRIX_MCP_EMBEDDINGS_URL, or unset BITRIX_MCP_SEMANTIC_ENABLED if you only need SQLite FTS docs search. | | WARNING embeddingsService: ... document count differs | SQLite docs were reindexed after embeddings were last populated. | Run bitrix-mcp index-embeddings after bitrix-mcp index-docs, or run bitrix-mcp index-docs --embeddings while the service is running. |

You can also POST chunks to /index manually:

{
  "documents": [
    {
      "id": "framework/events",
      "text": "Bitrix events are registered with AddEventHandler...",
      "metadata": { "uri": "bitrix-docs://framework/events.md" }
    }
  ]
}

Search through /search or, when BITRIX_MCP_SEMANTIC_ENABLED=1, the MCP tool bitrix_semantic_docs_search. The service also exposes /health, /stats, and /reload; /search keeps the JSON index and embedding matrix in memory after load/reload instead of rebuilding them for every request.

Agent configuration example

For a project at /var/www/site, the final per-project MCP config written by bitrix-mcp init looks like this. If /var/www/site/bitrix exists, BITRIX_ROOT is included; otherwise that line is omitted. Existing sibling servers such as another-server are preserved.

{
  "mcpServers": {
    "another-server": {
      "command": "another-tool",
      "args": ["serve"]
    },
    "bitrix-mcp": {
      "command": "bitrix-mcp",
      "args": ["serve"],
      "env": {
        "BITRIX_MCP_WORKSPACE": "/var/www/site",
        "BITRIX_MCP_DATA_DIR": "/var/www/site/.bitrix-mcp",
        "BITRIX_MCP_DOCS_PATHS": "/var/www/site/docs:/var/www/site/vendor-docs",
        "BITRIX_MCP_DOCS_DIR": "/var/www/site/docs",
        "BITRIX_ROOT": "/var/www/site",
        "BITRIX_MCP_EMBEDDINGS_URL": "http://127.0.0.1:8765",
        "BITRIX_MCP_SEMANTIC_ENABLED": "0"
      }
    }
  }
}

Development

npm test
npm run typecheck
npm run build

Phase 17 benchmark reporting

Run benchmark reporting from this repository or from an installed package:

npm run benchmark
# or, after build/install
bitrix-mcp benchmark

Reports are written to .bitrix-mcp/benchmark.json and .bitrix-mcp/benchmark.md. The benchmark measures incremental index-all, index-project, index-template, optional index-bitrix, docs search, LiveAPI search, event search, relation search, graph traversal, impact-radius, detect-changes, SQLite DB size, indexed files, symbols, events, relations, and docs chunks. It skips missing Bitrix roots, missing docs, and unavailable optional indexes with warnings. It does not force a full reindex unless --force is passed.

Documentation map

• MCP tools — implemented tools only, with parameters, examples, prompts, usage guidance, and limitations.
• Indexing — indexing scopes and benchmark reporting.
• Bitrix events — event-search workflow.
• ORM — D7 entity and usage workflow.
• Components — component/template workflow.
• Graph — bitrix_relations, neighbors, traversal, and impact radius.
• Detect changes — review workflow.
• Security — local data, path restrictions, and network notes.
• Examples — copy-ready prompts.

Recommended AI workflow:

1. General project work: bitrix_index_status → bitrix_project_overview → bitrix_liveapi_search / bitrix_docs_search as needed → bitrix_read_file_context or bitrix_read_symbol_context.
2. Review work: bitrix_detect_changes → bitrix_impact_radius → bitrix_graph_neighbors or bitrix_graph_traverse → bitrix_relation_search → context tools.
3. Bitrix events: bitrix_event_search → bitrix_relation_search → bitrix_graph_neighbors → bitrix_read_file_context.
4. ORM: bitrix_orm_search → bitrix_orm_entity_map → bitrix_orm_usage_search → bitrix_graph_neighbors.
5. Components: bitrix_component_search → bitrix_component_context → bitrix_impact_radius when changing component files.