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

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:

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

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