Bitrix24

Interact with and manage your Bitrix24 CRM instance through a powerful set of tools.

Bitrix24 MCP Server

A comprehensive Model Context Protocol (MCP) server for Bitrix24 CRM integration, enabling AI agents to seamlessly interact with your Bitrix24 instance through a powerful set of tools.

šŸš€ Features

  • Complete CRM Management: Create, read, update, and list contacts, deals, and tasks
  • Advanced Search: Search across all CRM entities with flexible filtering
  • Rate Limiting: Built-in rate limiting to respect Bitrix24 API limits
  • Type Safety: Full TypeScript implementation with comprehensive type definitions
  • Error Handling: Robust error handling and validation
  • Easy Integration: Simple setup with Claude Desktop and other MCP-compatible clients

šŸ“‹ Available Tools

Contact Management

  • bitrix24_create_contact - Create new contacts
  • bitrix24_get_contact - Retrieve contact by ID
  • bitrix24_list_contacts - List contacts with filtering
  • bitrix24_update_contact - Update existing contacts

Deal Management

  • bitrix24_create_deal - Create new deals
  • bitrix24_get_deal - Retrieve deal by ID
  • bitrix24_list_deals - List deals with filtering
  • bitrix24_update_deal - Update existing deals

Task Management

  • bitrix24_create_task - Create new tasks
  • bitrix24_get_task - Retrieve task by ID
  • bitrix24_list_tasks - List tasks with filtering
  • bitrix24_update_task - Update existing tasks

Utilities

  • bitrix24_search_crm - Search across CRM entities
  • bitrix24_get_current_user - Get current user info
  • bitrix24_validate_webhook - Validate webhook connection

šŸ› ļø Installation

Prerequisites

  • Node.js 18+
  • npm or yarn
  • Bitrix24 webhook URL

Setup

  1. Clone and install dependencies:
git clone <repository-url>
cd bitrix24-mcp-server
npm install
  1. Configure environment:
cp .env.example .env
# Edit .env with your Bitrix24 webhook URL
  1. Build the project:
npm run build
  1. Test the connection:
npm test

āš™ļø Configuration

Environment Variables

Create a .env file with the following variables:

BITRIX24_WEBHOOK_URL=https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/
NODE_ENV=development
LOG_LEVEL=info

Bitrix24 Webhook Setup

  1. Go to your Bitrix24 instance
  2. Navigate to Applications → Webhooks
  3. Create an Incoming webhook
  4. Copy the webhook URL (format: https://domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/)
  5. Set appropriate permissions for CRM and Tasks

šŸ”§ Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bitrix24": {
      "command": "node",
      "args": ["/path/to/your/bitrix24-mcp-server/build/index.js"],
      "env": {
        "BITRIX24_WEBHOOK_URL": "https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/"
      }
    }
  }
}

šŸ“– Usage Examples

Creating a Contact

Create a new contact named John Smith with email john@example.com and phone +39 123 456 789

Creating a Deal with Contact

Create a new contact for Maria Rossi with email maria@company.com, then create a deal titled "Website Development Project" for €5000 and link it to this contact

Managing Tasks

Create a task titled "Follow up with client" with high priority, deadline tomorrow, and link it to contact ID 123

Searching CRM

Search for all contacts and deals related to "example.com"

šŸ—ļø Development

Project Structure

bitrix24-mcp-server/
ā”œā”€ā”€ src/
│   ā”œā”€ā”€ bitrix24/
│   │   └── client.ts          # Bitrix24 API client
│   ā”œā”€ā”€ tools/
│   │   └── index.ts           # MCP tools definitions
│   ā”œā”€ā”€ utils/
│   │   └── logger.ts          # Logging utilities
│   ā”œā”€ā”€ config/
│   │   └── index.ts           # Configuration management
│   └── index.ts               # Main MCP server
ā”œā”€ā”€ test/
│   └── integration.test.js    # Integration tests
ā”œā”€ā”€ build/                     # Compiled JavaScript
ā”œā”€ā”€ package.json
ā”œā”€ā”€ tsconfig.json
└── README.md

Development Commands

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development
npm run dev

# Run tests
npm test

# Start the server
npm start

Adding New Tools

  1. Define the tool in src/tools/index.ts:
export const newTool: Tool = {
  name: 'bitrix24_new_action',
  description: 'Description of the new action',
  inputSchema: {
    type: 'object',
    properties: {
      // Define parameters
    },
    required: ['requiredParam']
  }
};
  1. Add the execution handler:
case 'bitrix24_new_action':
  // Implementation
  return { success: true, result: 'Action completed' };
  1. Add to allTools array and rebuild.

šŸ”’ Security Considerations

  • Webhook Security: Keep your webhook URL secret and rotate it regularly
  • Environment Variables: Never commit .env files to version control
  • Rate Limiting: The client includes built-in rate limiting (2 requests/second)
  • Error Handling: Sensitive information is not exposed in error messages

šŸ› Troubleshooting

Common Issues

"Webhook validation failed"

  • Verify your webhook URL is correct
  • Check that the webhook has appropriate permissions
  • Ensure your Bitrix24 instance is accessible

"Cannot find module" errors

  • Run npm install to install dependencies
  • Ensure you've built the project with npm run build

Rate limiting errors

  • The client automatically handles rate limiting
  • If you see persistent rate limit errors, consider reducing request frequency

Debug Mode

Set NODE_ENV=development and LOG_LEVEL=debug in your .env file for detailed logging.

šŸ“ API Reference

Bitrix24Client Methods

Contacts

  • createContact(contact: BitrixContact): Promise<string>
  • getContact(id: string): Promise<BitrixContact>
  • updateContact(id: string, contact: Partial<BitrixContact>): Promise<boolean>
  • listContacts(params?: ListParams): Promise<BitrixContact[]>

Deals

  • createDeal(deal: BitrixDeal): Promise<string>
  • getDeal(id: string): Promise<BitrixDeal>
  • updateDeal(id: string, deal: Partial<BitrixDeal>): Promise<boolean>
  • listDeals(params?: ListParams): Promise<BitrixDeal[]>

Tasks

  • createTask(task: BitrixTask): Promise<string>
  • getTask(id: string): Promise<BitrixTask>
  • updateTask(id: string, task: Partial<BitrixTask>): Promise<boolean>
  • listTasks(params?: TaskListParams): Promise<BitrixTask[]>

Utilities

  • getCurrentUser(): Promise<any>
  • searchCRM(query: string, entityTypes?: string[]): Promise<any>
  • validateWebhook(): Promise<boolean>

šŸ¤ Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

šŸ“„ License

MIT License - see LICENSE file for details.

šŸ†˜ Support

For issues and questions:

  1. Check the troubleshooting section
  2. Review Bitrix24 API documentation
  3. Open an issue on GitHub

Built with ā¤ļø for the AI automation community

Related Servers