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 ### 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:** ```bash git clone <repository-url> cd bitrix24-mcp-server npm install ``` 2. **Configure environment:** ```bash cp .env.example .env # Edit .env with your Bitrix24 webhook URL ``` 3. **Build the project:** ```bash npm run build ``` 4. **Test the connection:** ```bash npm test ``` ## ⚙️ Configuration ### Environment Variables Create a `.env` file with the following variables: ```env 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` ```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 ```bash # 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`: ```typescript 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: ```typescript 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[]>` #### 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**