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

User Management

• bitrix24_get_user - Get user information by ID

• bitrix24_get_all_users - Get all users in the system with names and details

• bitrix24_resolve_user_names - Resolve user IDs to user names

• bitrix24_get_contacts_with_user_names - Get contacts with user names resolved

• bitrix24_get_deals_with_user_names - Get deals with user names resolved

• bitrix24_get_leads_with_user_names - Get leads with user names resolved

• bitrix24_get_companies_with_user_names - Get companies with user names resolved

Lead Management

• bitrix24_create_lead - Create new leads

• bitrix24_get_lead - Retrieve lead by ID

• bitrix24_list_leads - List leads with filtering

• bitrix24_get_latest_leads - Get most recent leads

• bitrix24_get_leads_from_date_range - Get leads from specific date range

• bitrix24_update_lead - Update existing leads

Company Management

• bitrix24_create_company - Create new companies

• bitrix24_get_company - Retrieve company by ID

• bitrix24_list_companies - List companies with filtering

• bitrix24_get_latest_companies - Get most recent companies

• bitrix24_get_companies_from_date_range - Get companies from specific date range

• bitrix24_update_company - Update existing companies

Enhanced Deal Filtering

• bitrix24_get_deal_pipelines - Get all deal pipelines/categories

• bitrix24_get_deal_stages - Get deal stages for pipelines

• bitrix24_filter_deals_by_pipeline - Filter deals by pipeline

• bitrix24_filter_deals_by_budget - Filter deals by budget range

• bitrix24_filter_deals_by_status - Filter deals by stage/status

Utilities

• bitrix24_search_crm - Search across CRM entities

• bitrix24_get_current_user - Get current user info

• bitrix24_validate_webhook - Validate webhook connection

• bitrix24_diagnose_permissions - Diagnose webhook permissions

• bitrix24_check_crm_settings - Check CRM settings and configuration

• bitrix24_test_leads_api - Test leads API endpoints

Sales Team Monitoring

• bitrix24_monitor_user_activities - Monitor user activities (calls, emails, timeline interactions, response times)

• bitrix24_get_user_performance_summary - Get comprehensive performance summary with deal metrics and conversion rates

• bitrix24_analyze_account_performance - Analyze performance for specific accounts (companies/contacts)

• bitrix24_compare_user_performance - Compare performance metrics between multiple users

• bitrix24_track_deal_progression - Track deal progression through pipeline stages with timing analysis

• bitrix24_monitor_sales_activities - Monitor sales-related activities (tasks, follow-ups, meetings)

• bitrix24_generate_sales_report - Generate comprehensive sales reports with customizable metrics

• bitrix24_get_team_dashboard - Get real-time team performance dashboard

• bitrix24_analyze_customer_engagement - Analyze customer engagement patterns and relationship health

• bitrix24_forecast_performance - Generate performance forecasts and predictive analytics

🛠️ Installation

Prerequisites

• Node.js 18+

• npm or yarn

• Bitrix24 webhook URL

Setup

1. Clone and install dependencies:

2. Configure environment:

3. Build the project:

4. Test the connection:

⚙️ Configuration

Environment Variables

Create a .env file with the following variables:

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

📖 Usage Examples

Creating a Contact

Creating a Deal with Contact

Managing Tasks

Searching CRM

🏗️ Development

Project Structure

Development Commands

Adding New Tools

1. Define the tool in src/tools/index.ts:

2. Add the execution handler:

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[]>

Users

• getUser(userId: string): Promise<any>

• getAllUsers(): Promise<any[]>

• getUsersByIds(userIds: string[]): Promise<any[]>

• resolveUserNames(userIds: string[]): Promise<Record<string, string>>

• enhanceWithUserNames<T>(items: T[], userIdFields?: string[]): Promise<T[]>

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