gunnit/bitrix24-mcp-server

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

2. Configure environment:

cp .env.example .env
# Edit .env with your Bitrix24 webhook URL

3. Build the project:

npm run build

4. 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']
  }
};

2. Add the execution handler:

case 'bitrix24_new_action':
  // Implementation
  return { success: true, result: 'Action completed' };

3. 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