EspoCRM MCP Server

A comprehensive Model Context Protocol (MCP) server for seamless integration with EspoCRM. This server enables AI assistants to interact with your EspoCRM instance through a standardized interface, providing complete CRUD operations for Contacts, Accounts, Opportunities, Meetings, Users, Tasks, Leads, and advanced system management capabilities.

** NEW: AI Chatbot Integration** - Now includes a complete chatbot interface that embeds directly into your EspoCRM, providing natural language access to all 47 MCP tools!

Features

Core Capabilities

• Complete CRUD Operations - Create, read, update, and delete entities
• Multi-Entity Support - Contacts, Accounts, Opportunities, Meetings, Users, Tasks, and Leads
• Advanced Search & Filtering - Flexible search with date ranges, pagination, and complex filters
• Task Management - Complete task lifecycle with parent relationships and user assignment
• Lead Management - Full lead pipeline from creation to conversion
• Meeting Management - Full calendar integration with attendee management
• User Management - Comprehensive user search and lookup capabilities
• Real-time Validation - Zod-based schema validation for all operations
• Comprehensive Logging - Winston-powered logging with multiple levels

Authentication & Security

• Multiple Auth Methods - API Key and HMAC authentication support
• Secure Configuration - Environment-based configuration management
• Rate Limiting - Built-in rate limiting for API protection
• Error Handling - Robust error handling with detailed logging

Calendar Integration

• Meeting Operations - Create, search, update, and manage meetings
• Attendee Management - Link contacts and users to meetings
• Date/Time Filtering - Advanced date range search capabilities
• Google Calendar Sync Compatibility - Designed for calendar synchronization workflows

AI Chatbot Integration

• Floating Chat Widget - Beautiful, non-intrusive chat bubble interface
• Natural Language Processing - Chat in plain English to perform CRM operations
• Real-time Communication - WebSocket-powered instant responses
• 47 MCP Tools Access - Complete CRM functionality via chat
• EspoCRM Embedding - Integrates directly into your EspoCRM interface
• Mobile Responsive - Works seamlessly on all devices

Developer Experience

• TypeScript - Full TypeScript support with strict typing
• Docker Support - Containerized deployment ready
• Comprehensive Testing - Multiple test scripts and validation tools
• MCP 2024/2025 Compliant - Latest MCP specification support

Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• EspoCRM instance with API access
• Valid API credentials

Installation

1. Clone the repository

git clone https://github.com/zaphod-black/EspoMCP.git
cd EspoMCP

1. Install dependencies

npm install

1. Configure environment

cp .env.example .env
# Edit .env with your EspoCRM credentials

1. Build the project

npm run build

1. Test the connection

npm run test:config

AI Chatbot Quick Start

Deploy Chatbot Interface

1. Navigate to chatbot directory

cd chatbot-bridge

1. Install dependencies

npm install

1. Configure environment

cp .env.example .env
# Edit .env with your EspoCRM settings

1. Start chatbot server

npm start
# Or with Docker: docker-compose up -d

1. Integrate with EspoCRM Add to your EspoCRM footer template:

<script>
  window.ESPOCRM_CHAT_SERVER = 'http://your-server:3001';
</script>
<script src="http://your-server:3001/socket.io/socket.io.js"></script>
<script src="http://your-server:3001/api/widget.js"></script>

1. Try the Demo Visit http://localhost:3001/widget to see the chatbot in action!

Environment Configuration

Create a .env file with your EspoCRM configuration:

# EspoCRM Configuration
ESPOCRM_URL=https://your-espocrm-instance.com
ESPOCRM_API_KEY=your-api-key-here
ESPOCRM_AUTH_METHOD=apikey

# Optional: HMAC Authentication
# ESPOCRM_SECRET_KEY=your-secret-key
# ESPOCRM_AUTH_METHOD=hmac

# Server Configuration (Optional)
MCP_TRANSPORT=stdio
RATE_LIMIT=100
REQUEST_TIMEOUT=30000
LOG_LEVEL=info

Required Configuration

Available Tools

The MCP server provides 47 comprehensive tools for EspoCRM integration:

Contact Management

• create_contact - Create new contacts with full field support
• search_contacts - Search and filter contacts with date range filtering
• get_contact - Retrieve specific contact by ID

Account Management

• create_account - Create new company/organization accounts
• search_accounts - Search and filter accounts with date range filtering

Opportunity Management

• create_opportunity - Create new sales opportunities
• search_opportunities - Search opportunities with advanced filters including amount ranges

Meeting Management

• create_meeting - Create meetings with attendee management and calendar integration
• search_meetings - Search meetings with date ranges, status, and location filters
• get_meeting - Retrieve detailed meeting information including attendees
• update_meeting - Update existing meetings with support for all meeting fields

User Management

• search_users - Search users by username, email, name, type, and status
• get_user_by_email - Direct email-based user lookup for calendar sync operations

Task Management

• create_task - Create tasks with parent entity support (Lead, Account, Contact, Opportunity)
• search_tasks - Search tasks by assignee, status, priority, parent entity, and due dates
• get_task - Retrieve detailed task information including relationships
• update_task - Update task properties including status, priority, and due date
• assign_task - Assign or reassign tasks to specific users

Lead Management

• create_lead - Create new leads with full field support and validation
• search_leads - Search leads by status, source, assignee, and date ranges
• update_lead - Update lead properties and status
• convert_lead - Convert leads to contacts, accounts, and/or opportunities
• assign_lead - Assign or reassign leads to specific users

Team & Role Management

• add_user_to_team - Add users to teams with optional position assignment
• remove_user_from_team - Remove users from teams
• assign_role_to_user - Assign roles to users for permissions management
• get_user_teams - Get all teams that a user belongs to
• get_team_members - Get all members of a specific team
• search_teams - Search teams by name and description
• get_user_permissions - Get effective permissions for a user based on roles

Generic Entity Operations

• create_entity - Create records for any entity type (including custom entities)
• search_entity - Search any entity type with flexible filters and field selection
• update_entity - Update any entity record by ID with flexible data
• delete_entity - Delete any entity record by ID
• get_entity - Get specific entity records with optional field selection

Relationship Management

• link_entities - Create relationships between any two entity records
• unlink_entities - Remove relationships between entity records
• get_entity_relationships - Get all related records for an entity with relationship details

Communication Tools

• create_call - Create call records with status, direction, and duration tracking
• search_calls - Search calls by status, direction, contact, and date ranges
• create_case - Create support cases with priority, type, and account linking
• search_cases - Search cases by status, priority, type, and assignment
• add_note - Add notes to any entity record for documentation and follow-up
• search_notes - Search notes by parent entity, author, and date ranges
• create_document - Create document records with file attachments and metadata

System Tools

• health_check - Verify server and EspoCRM connectivity across all entities

Enhanced Search Capabilities

All search tools now support advanced filtering options:

Date Range Filtering

• createdFrom / createdTo - Filter by creation date range
• modifiedFrom / modifiedTo - Filter by modification date range
• dateFrom / dateTo - Filter meetings by date range

Meeting-Specific Filters

• status - Filter by meeting status (Planned, Held, Not Held)
• location - Filter by meeting location
• assignedUserName - Filter by assigned user

User-Specific Filters

• userName - Search by username
• emailAddress - Search by email address
• firstName / lastName - Search by name components
• isActive - Filter by active status
• type - Filter by user type (admin, regular, portal, api)

Usage Examples

Task Management

// Create a task assigned to a user with parent relationship
await client.callTool('create_task', {
  name: 'Follow up on lead discussion',
  assignedUserId: 'user123',
  par

---