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 
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`
• `getContact(id: string): Promise`
• `updateContact(id: string, contact: Partial): Promise`
• `listContacts(params?: ListParams): Promise`

Deals

• `createDeal(deal: BitrixDeal): Promise`
• `getDeal(id: string): Promise`
• `updateDeal(id: string, deal: Partial): Promise`
• `listDeals(params?: ListParams): Promise`

Tasks

• `createTask(task: BitrixTask): Promise`
• `getTask(id: string): Promise`
• `updateTask(id: string, task: Partial): Promise`
• `listTasks(params?: TaskListParams): Promise`

Users

• `getUser(userId: string): Promise`
• `getAllUsers(): Promise`
• `getUsersByIds(userIds: string[]): Promise`
• `resolveUserNames(userIds: string[]): Promise>`
• `enhanceWithUserNames(items: T[], userIdFields?: string[]): Promise`

Utilities

• `getCurrentUser(): Promise`
• `searchCRM(query: string, entityTypes?: string[]): Promise`
• `validateWebhook(): Promise`

🤝 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