Content
# Bitrix24 MCP Server
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/release/python-3120/)
[](https://github.com/astral-sh/ruff)
Integration server using Model Context Protocol (MCP) to provide access to Bitrix24 data and functions for large language models (LLM) and other AI agents. LLMs can securely interact with your CRM data (contacts, deals) using predefined "tools" and "resources" provided by this server via the standard MCP protocol.
## Key Features
* **Integration with Bitrix24:** Access to contacts and deals via the Bitrix24 REST API.
* **Model Context Protocol (MCP):** Provides a standardized interface for interacting with AI models.
* **Tools:** Functions that AI can call (e.g., search for contacts, update deal stage).
* **Resources:** Data that AI can request (e.g., information about a specific contact or a list of active deals).
* **Prompts:** Templates for generating requests to AI.
* **Asynchronous:** Built on `asyncio` for efficient request processing.
* **Dependency Injection:** Uses `wireup` for dependency management.
* **Configurability:** Settings are managed via environment variables.
* **Structured Logging:** Uses `structlog` for easy event tracking.
* **Extensibility:** Easily add support for new Bitrix24 entities or new MCP tools/resources.
## Technologies
* Python 3.12+
* [Fast-Bitrix24](https://github.com/leshchenko1979/fast_bitrix24): Client for Bitrix24 REST API
* [MCP (Model Context Protocol)](https://github.com/mentalcalculation/mcp): Framework for creating MCP servers (`fastmcp`)
* [Pydantic & Pydantic-Settings](https://docs.pydantic.dev/): Data validation and settings management
* [Structlog](https://www.structlog.org/): Structured logging
* [Ruff](https://github.com/astral-sh/ruff): Linter and code formatter
* Asyncio
* [Dishka](https://pypi.org/project/dishka/): CLI utilities for dependency and script management
## Getting Started
### Prerequisites
1. **Python:** Version 3.12 or higher.
2. **Bitrix24:**
* Bitrix24 account (cloud or on-premise).
* Incoming webhook with the necessary permissions (at least `crm`). [How to create a webhook](https://helpdesk.bitrix24.ru/open/20886106/).
### Configuration
The server requires the `BITRIX_WEBHOOK_URL` environment variable to be set:
```bash
export BITRIX_WEBHOOK_URL="https://your-domain.bitrix24.ru/rest/1/yoursecretcode/"
```
### Running the Server
Run the MCP server:
```bash
uvx bitrix24-mcp
```
You will see logs in the console, including information about registered MCP tools and resources.
### Running the Test Script
To check the basic functionality of the integration with the Bitrix24 API, you can run the test script:
```bash
python test_services.py
```
The script will perform several requests to the Bitrix24 API (getting a list of contacts, getting a contact by ID, etc.) and output the results.
## Usage
The running MCP server is ready to accept requests from MCP-compatible clients or LLMs.
### Available MCP Tools
Tools are functions that AI can ask to perform.
* `tool://get_contact`
* **Description:** Get contact information by ID.
* **Parameters:** `contact_id: int`
* **Returns:** JSON string with contact data.
* `tool://search_contacts`
* **Description:** Search for contacts by name, phone, or email.
* **Parameters:** `query: str`, `search_type: str = "name"` (`name`, `phone`, `email`), `limit: int = 10`
* **Returns:** JSON string with a list of found contacts.
* `tool://list_contacts`
* **Description:** Get a list of contacts with filtering options.
* **Parameters:** `limit: int = 50`, `company_id: int | None = None`
* **Returns:** JSON string with a list of contacts.
* `tool://get_deal`
* **Description:** Get deal information by ID.
* **Parameters:** `deal_id: int`
* **Returns:** JSON string with deal data.
* `tool://list_deals`
* **Description:** Get a list of deals with filtering options.
* **Parameters:** `active_only: bool = False`, `contact_id: int | None = None`, `company_id: int | None = None`, `limit: int = 50`
* **Returns:** JSON string with a list of deals.
* `tool://update_deal_stage`
* **Description:** Update the deal stage.
* **Parameters:** `deal_id: int`, `stage_id: str` (e.g., `C14:WON`)
* **Returns:** JSON string with the operation result (`{"success": true/false, "message": "..."}`).
### Available MCP Resources
Resources are data that AI can request by URI.
* `contact://{contact_id}`
* **Description:** Get contact data by ID in a readable format.
* **Example:** `contact://123`
* **Returns:** Text representation of contact data.
* `deal://{deal_id}`
* **Description:** Get deal data by ID in a readable format.
* **Example:** `deal://456`
* **Returns:** Text representation of deal data.
* `deals://active`
* **Description:** Get a list of active deals in a readable format.
* **Example:** `deals://active`
* **Returns:** Text representation of a list of active deals.
## Development and Contribution
We welcome contributors!
### Setting Up the Development Environment
1. Follow the steps in the [Installation](#installation) section.
2. Install development dependencies:
```bash
uv sync
```
### Code Quality
* **Formatting and Linting:** `ruff` is used. It is recommended to run before committing:
```bash
ruff format .
ruff check . --fix
```
* **Typing:** The project uses strict Python typing.
### Change Process
1. **Create an Issue:** Describe the problem or proposed improvement in the Issues section of the repository.
2. **Fork the repository:** Create your copy of the project.
3. **Create a branch:** `git checkout -b feature/your-feature-name` or `bugfix/issue-number`.
4. **Make changes:** Write code and tests (if applicable).
5. **Check code quality:** Run `ruff`.
6. **Make a commit:** `git commit -m "feat: Add support for Bitrix24 Leads"` (follow [Conventional Commits](https://www.conventionalcommits.org/) if possible).
7. **Send changes to your fork:** `git push origin feature/your-feature-name`.
8. **Create a Pull Request:** Open a Pull Request from your branch to the `main` branch of the main repository. Describe the changes made and link the PR to the created Issue.
## License
This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
