Content
# Bitrix24 MCP Server
## Overview
Bitrix24 MCP (Model-Controller-Presenter) Server is a server-side application that provides a REST API for interacting with Bitrix24 CRM. The server uses the MCP architectural pattern to organize the code and ensure clear separation of responsibilities between components.
## Features
- Full access to basic Bitrix24 CRM entities (deals, leads, contacts, tasks, etc.)
- Data formatting for convenient use on the client-side
- Request and response logging
- Error and exception handling
- CORS support for interaction with frontend applications
## Requirements
- Node.js (version 14.x or higher)
- npm (version 6.x or higher)
- Access to Bitrix24 with a configured webhook
## Installation
1. Clone the repository:
```bash
git clone https://github.com/your-username/bitrix24-mcp-server.git
cd bitrix24-mcp-server
```
2. Install dependencies:
```bash
npm install
```
3. Create a `.env` file in the project root directory with the following parameters:
```
PORT=3000
BITRIX_DOMAIN=your-domain.bitrix24.ru
BITRIX_WEBHOOK_TOKEN=your-webhook-token
LOG_LEVEL=info
```
4. Start the server:
```bash
npm start
```
## Architecture
The server is built based on the MCP (Model-Controller-Presenter) architectural pattern:
- **Model (Bitrix24Model)**: Responsible for interacting with the Bitrix24 API and processing data.
- **Controller (Bitrix24Controller)**: Handles HTTP requests, applies business logic, and coordinates the work of the model and presenter.
- **Presenter (Bitrix24Presenter)**: Formats data for presentation to the client.
## API Endpoints
### Tasks
- `GET /api/tasks` - Get a list of tasks
- Query parameters:
- `filter` - JSON string with filters (optional)
### Contacts
- `GET /api/contacts` - Get a list of contacts
- Query parameters:
- `filter` - JSON string with filters (optional)
### Deals
- `GET /api/deals` - Get a list of deals
- Query parameters:
- `filter` - JSON string with filters (optional)
- `GET /api/deals/:id` - Get a deal by ID
- `POST /api/deals` - Create a new deal
- Body: deal data object
- `PUT /api/deals/:id` - Update a deal
- Body: deal data object for update
- `GET /api/deal-categories` - Get sales funnels
- `GET /api/deal-stages/:categoryId?` - Get deal stages for a specified funnel
### Leads
- `GET /api/leads` - Get a list of leads
- Query parameters:
- `filter` - JSON string with filters (optional)
- `GET /api/leads/:id` - Get a lead by ID
- `POST /api/leads` - Create a new lead
- Body: lead data object
- `PUT /api/leads/:id` - Update a lead
- Body: lead data object for update
- `GET /api/lead-statuses` - Get lead statuses
### Activities
- `GET /api/activities` - Get a list of activities
- Query parameters:
- `filter` - JSON string with filters (optional)
- `GET /api/activities/:id` - Get an activity by ID
- `POST /api/activities` - Create a new activity
- Body: activity data object
- `PUT /api/activities/:id` - Update an activity
- Body: activity data object for update
### Users
- `GET /api/users` - Get a list of users
- Query parameters:
- `filter` - JSON string with filters (optional)
- `GET /api/users/:id` - Get a user by ID
### Timeline
- `POST /api/timeline-comment/:entityType/:entityId` - Add a comment to the timeline
- Body: `{ "comment": "Comment text" }`
### Telephony
- `GET /api/call-statistics` - Get call statistics
- Query parameters:
- `filter` - JSON string with filters (optional)
### Files
- `GET /api/files/:id` - Get file information
- `GET /api/files/:id/download` - Download a file
## Usage Examples
### Get a list of deals
```javascript
// Client-side code
async function getDeals() {
try {
const response = await fetch('http://localhost:3000/api/deals');
const data = await response.json();
console.log(data.deals);
} catch (error) {
console.error('Error getting deals:', error);
}
}
```
### Create a new lead
```javascript
// Client-side code
async function createLead() {
try {
const leadData = {
TITLE: 'New lead from the site',
NAME: 'Ivan',
LAST_NAME: 'Ivanov',
STATUS_ID: 'NEW',
PHONE: [{ VALUE_TYPE: 'WORK', VALUE: '+7 (999) 123-45-67' }],
EMAIL: [{ VALUE_TYPE: 'WORK', VALUE: 'ivan@example.com' }]
};
const response = await fetch('http://localhost:3000/api/leads', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(leadData)
});
const result = await response.json();
console.log('Lead created:', result);
} catch (error) {
console.error('Error creating lead:', error);
}
}
```
### Update a deal
```javascript
// Client-side code
async function updateDeal(dealId, stageId) {
try {
const dealData = {
STAGE_ID: stageId
};
const response = await fetch(`http://localhost:3000/api/deals/${dealId}`, {
method: 'PUT',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(dealData)
});
const result = await response.json();
console.log('Deal updated:', result);
} catch (error) {
console.error('Error updating deal:', error);
}
}
```
## Logging
The server uses a built-in logging mechanism to track requests and responses. The logging level can be configured in the `.env` file using the `LOG_LEVEL` parameter.
Available logging levels:
- `error` - only errors
- `warn` - warnings and errors
- `info` - informational messages, warnings, and errors (default)
- `debug` - debug information and all of the above
## Error Handling
The server handles errors and returns corresponding HTTP statuses and messages:
- `400 Bad Request` - incorrect request format
- `404 Not Found` - resource not found
- `500 Internal Server Error` - internal server error
Error response example:
```json
{
"error": "Error getting data from Bitrix24 API"
}
```
## Security
- Use HTTPS to protect data during transmission
- Store the webhook token in a secure location and do not include it in the code
- Regularly update the webhook token to minimize risks
## License
MIT
## MCP Server (mcp-server.js)
### Overview
`mcp-server.js` is an implementation of the MCP (Model Context Protocol) server for Bitrix24, which provides a set of tools for interacting with the Bitrix24 API through a REST API server. The MCP server works as an intermediate layer between the language model (LLM) and the REST API server Bitrix24, allowing the language model to perform operations with Bitrix24 data through structured tools.
### Principle of Operation
The MCP server uses the `@modelcontextprotocol/sdk` library to create and register tools that can be called by the language model. Each tool represents a function that:
1. Accepts parameters defined using the Zod schema
2. Performs a request to the REST API server Bitrix24
3. Returns the result in a structured format
The MCP server is launched through the stdio transport, which allows it to interact with the language model through standard input/output streams.
### Available Tools
The MCP server provides the following groups of tools:
#### Leads
- `getLeads` - get a list of leads with filtering capabilities
- `getLead` - get information about a specific lead by ID
- `createLead` - create a new lead
- `updateLead` - update an existing lead
- `getLeadStatuses` - get a list of lead statuses
#### Deals
- `getDeals` - get a list of deals with filtering capabilities
- `getDeal` - get information about a specific deal by ID
- `createDeal` - create a new deal
- `updateDeal` - update an existing deal
- `getDealCategories` - get a list of sales funnels
- `getDealStages` - get a list of deal stages for a specified funnel
#### Contacts
- `getContacts` - get a list of contacts with filtering capabilities
- `getContact` - get information about a specific contact by ID
#### Activities
- `getActivities` - get a list of activities with filtering capabilities
- `getActivity` - get information about a specific activity by ID
- `createActivity` - create a new activity
- `updateActivity` - update an existing activity
#### Users
- `getUsers` - get a list of users with filtering capabilities
- `getUser` - get information about a specific user by ID
#### Tasks
- `getTasks` - get a list of tasks with filtering capabilities
#### Telephony
- `getCallStatistics` - get call statistics
#### Files
- `getFile` - get information about a file by ID
#### Timeline
- `addTimelineComment` - add a comment to the timeline of an entity
#### Summary Information
- `getCrmSummary` - obtaining summary information about CRM (number of leads, deals, contacts, etc.)
#### Utility Tools
- `checkApiConnection` - checking connection to API server
### Configuration and Usage
1. Install dependencies:
```bash
cd mcp-server
npm install
```
2. Ensure that the REST API server Bitrix24 is running on port 3000 (or modify the value of `API_BASE_URL` in the file `mcp-server.js`).
3. Start the MCP server:
```bash
node mcp-server.js
```
4. Configure the language model to use the MCP server by adding it to the MCP server configuration.
### Configuring Claude Desktop to work with MCP server
To use the Bitrix24 MCP server with Claude Desktop, you need to create or edit the configuration file `claude_desctop_config.json`. This file should be located in the following directory:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
Example contents of the file `claude_desctop_config.json`:
```json
{
"mcpServers": {
"bitrix24": {
"command": "node",
"args": ["/full/path/to/mcp-server/mcp-server.js"],
"env": {},
"disabled": false,
"autoApprove": []
}
}
}
```
Where:
- `bitrix24` - a unique name for the MCP server that will be used to refer to it
- `command` - the command to start the server (usually `node`)
- `args` - an array of command arguments, including the full path to the file `mcp-server.js`
- `env` - an object with environment variables (can be left empty, as all settings are already included in `mcp-server.js`)
- `disabled` - a flag indicating whether the server is disabled (should be `false` for operation)
- `autoApprove` - an array of tool names that can be called without explicit confirmation by the user (recommended to leave empty for security)
After configuring the file, restart Claude Desktop, and the MCP server will be automatically started and connected to Claude. Now you can use the tools of the Bitrix24 MCP server in the dialogue with Claude.
### Example of using a tool through a language model
```javascript
// Example of calling the tool getLeads
const result = await model.useToolWithMcp("Bitrix24MCP", "getLeads", { filter: JSON.stringify({ STATUS_ID: "NEW" }) });
console.log(result); // Outputs a list of new leads
```
### Error Handling
Each tool includes error handling and returns a structured response even in case of problems. Errors are logged to the console for debugging.
### Extending Functionality
To add new tools, use the method `server.tool()`, specifying:
1. Tool name
2. Parameter scheme using Zod
3. Asynchronous handler function that performs the request and returns the result
