EspoCRM-MCP

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

Clone the repository

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

Install dependencies

npm install

Configure environment

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

Build the project

npm run build

Test the connection

npm run test:config

AI Chatbot Quick Start

Deploy Chatbot Interface

Navigate to chatbot directory

cd chatbot-bridge

Install dependencies

npm install

Configure environment

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

Start chatbot server

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

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>

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

Variable	Description	Required	Default
`ESPOCRM_URL`	Your EspoCRM instance URL	Yes	-
`ESPOCRM_API_KEY`	API key for authentication	Yes	-
`ESPOCRM_AUTH_METHOD`	Authentication method (`apikey` or `hmac`)	Yes	`apikey`
`ESPOCRM_SECRET_KEY`	Secret key for HMAC auth	No	-
`MCP_TRANSPORT`	MCP transport method	No	`stdio`
`RATE_LIMIT`	Requests per minute limit	No	`100`
`REQUEST_TIMEOUT`	Request timeout in milliseconds	No	`30000`
`LOG_LEVEL`	Logging level	No	`info`

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',
  parentType: 'Lead',
  parentId: 'lead456',
  priority: 'High',
  status: 'Not Started',
  dateEnd: '2025-08-15',
  description: 'Contact lead about pricing questions'
});

// Search tasks by assignee and status
await client.callTool('search_tasks', {
  assignedUserId: 'user123',
  status: 'Started',
  priority: 'High',
  dueDateFrom: '2025-08-01',
  dueDateTo: '2025-08-31'
});

// Assign task to different user
await client.callTool('assign_task', {
  taskId: 'task789',
  assignedUserId: 'user456'
});

Lead Management

// Create a new lead
await client.callTool('create_lead', {
  firstName: 'John',
  lastName: 'Smith',
  emailAddress: 'john.smith@example.com',
  accountName: 'Smith Industries',
  source: 'Web Site',
  status: 'New',
  assignedUserId: 'user123',
  description: 'Interested in enterprise solution'
});

// Search leads by status and source
await client.callTool('search_leads', {
  status: 'In Process',
  source: 'Web Site',
  assignedUserName: 'Sales Rep',
  createdFrom: '2025-08-01',
  limit: 20
});

// Convert lead to contact and account
await client.callTool('convert_lead', {
  leadId: 'lead123',
  createContact: true,
  createAccount: true,
  createOpportunity: true,
  opportunityName: 'Smith Industries - Enterprise Deal',
  opportunityAmount: 50000
});

Team & Role Management

// Add user to team with position
await client.callTool('add_user_to_team', {
  userId: 'user123',
  teamId: 'sales-team',
  position: 'Sales Manager'
});

// Get all members of a team
await client.callTool('get_team_members', {
  teamId: 'sales-team',
  limit: 50
});

// Assign role to user for permissions
await client.callTool('assign_role_to_user', {
  userId: 'user123',
  roleId: 'manager-role'
});

// Search teams by criteria
await client.callTool('search_teams', {
  name: 'Sales',
  description: 'revenue'
});

// Get user's effective permissions
await client.callTool('get_user_permissions', {
  userId: 'user123'
});

Generic Entity Operations

// Create any entity type (including custom entities)
await client.callTool('create_entity', {
  entityType: 'CustomProduct',
  data: {
    name: 'Premium Widget',
    price: 199.99,
    category: 'Electronics',
    inStock: true
  }
});

// Search any entity with flexible filters
await client.callTool('search_entity', {
  entityType: 'CustomOrder',
  filters: {
    status: 'pending',
    totalAmount: 1000,
    customerType: 'enterprise'
  },
  select: ['id', 'orderNumber', 'customerName', 'totalAmount'],
  orderBy: 'createdAt',
  order: 'desc'
});

// Update any entity record
await client.callTool('update_entity', {
  entityType: 'CustomProduct',
  entityId: 'prod123',
  data: {
    price: 179.99,
    inStock: false,
    lastModified: '2025-07-20T10:30:00Z'
  }
});

// Delete any entity record
await client.callTool('delete_entity', {
  entityType: 'CustomProduct',
  entityId: 'prod123'
});

// Get specific entity with field selection
await client.callTool('get_entity', {
  entityType: 'CustomOrder',
  entityId: 'order456',
  select: ['orderNumber', 'customerName', 'items', 'totalAmount']
});

Relationship Management

// Link entities together (e.g., link contact to account)
await client.callTool('link_entities', {
  entityType: 'Contact',
  entityId: 'contact123',
  relatedEntityType: 'Account',
  relatedEntityId: 'account456',
  relationshipName: 'accounts'
});

// Get all relationships for an entity
await client.callTool('get_entity_relationships', {
  entityType: 'Contact',
  entityId: 'contact123',
  relationshipName: 'opportunities'
});

// Remove relationship between entities
await client.callTool('unlink_entities', {
  entityType: 'Contact',
  entityId: 'contact123',
  relatedEntityType: 'Account',
  relatedEntityId: 'account456',
  relationshipName: 'accounts'
});

Communication Tools

// Create a call record
await client.callTool('create_call', {
  name: 'Follow-up call with John Smith',
  status: 'Held',
  direction: 'Outbound',
  duration: 1800, // 30 minutes in seconds
  parentType: 'Contact',
  parentId: 'contact123',
  description: 'Discussed pricing options and next steps'
});

// Search calls by criteria
await client.callTool('search_calls', {
  status: 'Held',
  direction: 'Outbound',
  dateFrom: '2025-07-01',
  dateTo: '2025-07-31',
  limit: 20
});

// Create a support case
await client.callTool('create_case', {
  name: 'Login Issues',
  status: 'New',
  priority: 'High',
  type: 'Technical',
  accountId: 'account123',
  description: 'Customer unable to login to portal'
});

// Add a note to any entity
await client.callTool('add_note', {
  parentType: 'Lead',
  parentId: 'lead123',
  post: 'Customer expressed interest in enterprise features. Schedule demo next week.',
  data: {
    isInternal: false
  }
});

// Search notes by parent entity
await client.callTool('search_notes', {
  parentType: 'Lead',
  parentId: 'lead123',
  createdFrom: '2025-07-01',
  limit: 10
});

AI Chatbot Usage

The embedded chatbot understands natural language and can perform any CRM operation:

// Natural language examples users can type:
"Create a contact named Sarah Johnson with email sarah@techcorp.com"
"Find all accounts in the software industry"
"Show me opportunities over $50,000"
"Create a task to follow up with lead John Smith"
"Schedule a meeting for tomorrow at 2 PM"
"What's the system health status?"
"Link contact ID 123 to account TechCorp"
"Add a note to case #456 saying 'Customer satisfied with resolution'"

Meeting Management

// Create a meeting with attendees
await client.callTool('create_meeting', {
  name: 'Project Kickoff Meeting',
  dateStart: '2025-08-01T10:00:00',
  dateEnd: '2025-08-01T11:00:00',
  location: 'Conference Room A',
  description: 'Initial project planning session',
  status: 'Planned',
  contactsIds: ['contact123', 'contact456'],
  usersIds: ['user789']
});

// Search meetings by date range
await client.callTool('search_meetings', {
  dateFrom: '2025-08-01',
  dateTo: '2025-08-31',
  status: 'Planned',
  limit: 20
});

User Management

// Find user by email
await client.callTool('get_user_by_email', {
  emailAddress: 'john.doe@company.com'
});

// Search active users
await client.callTool('search_users', {
  isActive: true,
  type: 'regular',
  limit: 50
});

Advanced Contact Search with Date Filtering

// Search contacts created in the last week
await client.callTool('search_contacts', {
  searchTerm: 'manager',
  createdFrom: '2025-07-13',
  createdTo: '2025-07-20',
  limit: 10
});

Calendar Integration Workflow

// Complete workflow for calendar sync
const meetings = await client.callTool('search_meetings', {
  dateFrom: '2025-08-01',
  dateTo: '2025-08-31'
});

const user = await client.callTool('get_user_by_email', {
  emailAddress: 'calendar@company.com'
});

const newMeeting = await client.callTool('create_meeting', {
  name: 'Synced from Google Calendar',
  dateStart: '2025-08-15T14:00:00',
  dateEnd: '2025-08-15T15:00:00',
  googleEventId: 'google_event_123'
});

Testing

Automated Testing

The project includes comprehensive testing tools:

# Test configuration and connectivity
npm run test:config

# Test MCP client functionality
npm run test:client

# Run unit tests
npm test

Manual Testing Scripts

Connection Testing

node test-connection.js

Tests basic connectivity, API endpoints, and authentication.

Enhanced Tools Testing

node test-enhanced-tools.js

Comprehensive test of all enhanced features including meetings and users.

Random Contact Generation

node create-random-contact.js

Creates a random test contact to verify CRUD operations.

Development

Project Structure

EspoMCP/
├── src/                     # Source code
│   ├── config/             # Configuration management
│   ├── espocrm/           # EspoCRM API client and types
│   │   ├── client.ts      # HTTP client with authentication
│   │   └── types.ts       # TypeScript interfaces for all entities
│   ├── tools/             # MCP tool implementations
│   ├── utils/             # Utility functions and formatting
│   │   ├── errors.ts      # Error handling utilities
│   │   ├── formatting.ts  # Entity formatting functions
│   │   ├── logger.ts      # Winston logger configuration
│   │   └── validation.ts  # Zod schema validation
│   └── index.ts           # Main server entry point
├── tests/                  # Test files
├── build/                  # Compiled JavaScript
├── logs/                   # Application logs
└── docs/                   # Documentation

Key Components

MCP Server (`src/index.ts`)

Main server implementation with environment loading, graceful shutdown handling, and MCP protocol compliance.

EspoCRM Client (`src/espocrm/client.ts`)

HTTP client with authentication, error handling, logging, and comprehensive CRUD operations.

Entity Types (`src/espocrm/types.ts`)

Complete TypeScript interfaces for Contact, Account, Opportunity, Meeting, User, and related entities.

Tool Registry (`src/tools/index.ts`)

Central registry for all MCP tools with proper type safety, validation, and error handling.

Formatting Utilities (`src/utils/formatting.ts`)

Professional formatting functions for all entity types with consistent output formatting.

Development Workflow

Make changes to source files in src/
Build the project with npm run build
Test changes with npm run test:config
Test enhanced features with npm run test:client
Lint code with npm run lint

Docker Deployment

Build and Run with Docker

# Build the Docker image
npm run docker:build

# Run with environment file
npm run docker:run

Docker Compose

version: '3.8'
services:
  espocrm-mcp:
    build: .
    environment:
      - ESPOCRM_URL=${ESPOCRM_URL}
      - ESPOCRM_API_KEY=${ESPOCRM_API_KEY}
      - ESPOCRM_AUTH_METHOD=apikey
      - MCP_TRANSPORT=stdio
      - RATE_LIMIT=100
      - LOG_LEVEL=info
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped

Calendar Sync Integration

This MCP server is specifically designed to work seamlessly with calendar synchronization systems:

Google Calendar Sync Compatibility

Meeting entities include googleEventId field for sync tracking
User lookup by email for attendee management
Date range filtering for efficient sync operations
Attendee linking through contactsIds and usersIds

Sync Prevention Features

Comprehensive entity tracking to prevent duplicate creation
Support for external system identifiers
Robust error handling for sync operations

Workflow Integration

// Typical calendar sync workflow
const existingMeetings = await client.callTool('search_meetings', {
  dateFrom: syncStartDate,
  dateTo: syncEndDate
});

const user = await client.callTool('get_user_by_email', {
  emailAddress: assignedUserEmail
});

// Create meetings from external calendar
for (const externalEvent of externalEvents) {
  await client.callTool('create_meeting', {
    name: externalEvent.title,
    dateStart: externalEvent.start,
    dateEnd: externalEvent.end,
    googleEventId: externalEvent.id,
    description: externalEvent.description
  });
}

Troubleshooting

Common Issues

Connection Failures

# Test basic connectivity
node test-connection.js

# Check environment variables
npm run test:config

# Test specific endpoints
curl -H "X-Api-Key: YOUR_API_KEY" http://your-espocrm.com/api/v1/App/user

Authentication Issues

Verify API key is correct and active
Check user permissions in EspoCRM
Ensure API access is enabled for the user
Verify the correct API endpoint format

Meeting Creation Issues

Ensure required fields (name, dateStart, dateEnd) are provided
Verify date format is ISO 8601 (YYYY-MM-DDTHH)
Check user permissions for meeting creation
Validate contact and user IDs exist before linking

User Search Issues

Verify user has permission to access User entity
Check if users exist in the system
Ensure email addresses are correctly formatted

Debug Mode

Enable debug logging:

LOG_LEVEL=debug

View detailed logs:

tail -f logs/espocrm-mcp.log

Connection Diagnostics

Test specific API endpoints:

# Test user endpoint
curl -H "X-Api-Key: YOUR_KEY" http://your-espocrm.com/api/v1/App/user

# Test meeting search
curl -H "X-Api-Key: YOUR_KEY" "http://your-espocrm.com/api/v1/Meeting?maxSize=1"

# Test user search  
curl -H "X-Api-Key: YOUR_KEY" "http://your-espocrm.com/api/v1/User?maxSize=1"

API Reference

Tool Schemas

All tools use Zod schemas for validation. Key schemas include:

Contact Schema

{
  firstName: string,
  lastName: string,
  emailAddress?: string,
  phoneNumber?: string,
  title?: string,
  department?: string,
  accountId?: string,
  description?: string
}

Meeting Schema

{
  name: string,
  dateStart: string,        // ISO 8601 format
  dateEnd: string,          // ISO 8601 format
  location?: string,
  description?: string,
  status?: 'Planned' | 'Held' | 'Not Held',
  parentType?: string,
  parentId?: string,
  contactsIds?: string[],   // Array of contact IDs
  usersIds?: string[],      // Array of user IDs
  googleEventId?: string    // For calendar sync
}

User Schema

{
  userName: string,
  firstName?: string,
  lastName?: string,
  emailAddress?: string,
  phoneNumber?: string,
  isActive?: boolean,
  type?: 'admin' | 'regular' | 'portal' | 'api'
}

Task Schema

{
  name: string,
  assignedUserId?: string,
  parentType?: 'Lead' | 'Account' | 'Contact' | 'Opportunity',
  parentId?: string,
  status?: 'Not Started' | 'Started' | 'Completed' | 'Canceled' | 'Deferred',
  priority?: 'Low' | 'Normal' | 'High' | 'Urgent',
  dateEnd?: string,         // Due date in YYYY-MM-DD format
  description?: string
}

Lead Schema

{
  firstName: string,
  lastName: string,
  emailAddress?: string,
  phoneNumber?: string,
  accountName?: string,     // Company name
  website?: string,
  status?: 'New' | 'Assigned' | 'In Process' | 'Converted' | 'Recycled' | 'Dead',
  source: 'Call' | 'Email' | 'Existing Customer' | 'Partner' | 'Public Relations' | 'Web Site' | 'Campaign' | 'Other',
  industry?: string,
  assignedUserId?: string,
  description?: string
}

Team Schema

{
  name: string,
  description?: string,
  positionList?: string[],  // Available positions in the team
}

Generic Entity Schema

{
  entityType: string,       // Entity type name (e.g., 'Contact', 'CustomProduct')
  data: {                   // Flexible key-value pairs
    [key: string]: any
  },
  // Optional for search/get operations
  filters?: {
    [field: string]: any
  },
  select?: string[],        // Fields to retrieve
  orderBy?: string,
  order?: 'asc' | 'desc'
}

Call Schema

{
  name: string,
  status?: 'Planned' | 'Held' | 'Not Held',
  direction?: 'Inbound' | 'Outbound',
  duration?: number,        // Duration in seconds
  parentType?: string,      // Related entity type
  parentId?: string,        // Related entity ID
  assignedUserId?: string,
  description?: string
}

Case Schema

{
  name: string,
  status?: 'New' | 'Assigned' | 'Pending' | 'Closed' | 'Rejected' | 'Duplicate',
  priority?: 'Low' | 'Normal' | 'High' | 'Urgent',
  type?: string,            // Case type
  accountId?: string,       // Related account
  contactId?: string,       // Related contact
  assignedUserId?: string,
  description?: string
}

Note Schema

{
  parentType: string,       // Entity type the note is attached to
  parentId: string,         // Entity ID the note is attached to
  post: string,             // Note content
  data?: {                  // Additional note data
    isInternal?: boolean,   // Internal note flag
    [key: string]: any
  }
}

Relationship Schema

{
  entityType: string,       // Source entity type
  entityId: string,         // Source entity ID
  relatedEntityType: string, // Target entity type
  relatedEntityId: string,  // Target entity ID
  relationshipName: string  // Relationship field name
}

Team Management Operations

// Add user to team
{
  userId: string,
  teamId: string,
  position?: string         // Optional position within team
}

// Role assignment
{
  userId: string,
  roleId: string
}

Search Parameters

{
  searchTerm?: string,
  limit?: number,           // Default: 20, Max: 200
  offset?: number,          // Default: 0
  createdFrom?: string,     // YYYY-MM-DD format
  createdTo?: string,       // YYYY-MM-DD format
  modifiedFrom?: string,    // YYYY-MM-DD format
  modifiedTo?: string,      // YYYY-MM-DD format
  // Entity-specific filters...
}

Response Formats

Standard List Response

{
  "total": 150,
  "list": [
    {
      "id": "entity123",
      "name": "Entity Name",
      "createdAt": "2025-07-20T10:30:00Z",
      "modifiedAt": "2025-07-20T15:45:00Z"
    }
  ]
}

Meeting Response

{
  "id": "meeting123",
  "name": "Project Meeting",
  "status": "Planned",
  "dateStart": "2025-08-01T10:00:00Z",
  "dateEnd": "2025-08-01T11:00:00Z",
  "location": "Conference Room A",
  "assignedUserName": "John Doe",
  "contacts": ["contact1", "contact2"],
  "googleEventId": "google_event_123"
}

Performance Considerations

Pagination

Default limit: 20 results
Maximum limit: 200 results
Use offset for pagination through large datasets

Rate Limiting

Default: 100 requests per minute
Configurable via RATE_LIMIT environment variable
Implements exponential backoff for rate limit handling

Caching

No built-in caching (recommended to implement at application level)
EspoCRM API responses are not cached to ensure data freshness

Bulk Operations

Individual entity operations only
For bulk operations, iterate through arrays at the application level
Consider rate limiting when processing large datasets

Security Best Practices

API Key Management

Store API keys in environment variables only
Rotate API keys regularly
Use dedicated API users with minimal required permissions
Monitor API usage logs

Network Security

Use HTTPS for all EspoCRM connections
Consider VPN or private networks for sensitive data
Implement IP whitelisting if supported by your EspoCRM instance

Data Validation

All inputs are validated using Zod schemas
Sanitization is applied to prevent injection attacks
Error messages do not expose sensitive system information

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/enhanced-search)
Commit your changes (git commit -m 'Add enhanced search capabilities')
Push to the branch (git push origin feature/enhanced-search)
Open a Pull Request

Development Guidelines

Follow TypeScript best practices with strict typing
Add comprehensive tests for new functionality
Update documentation for any new features
Ensure all tests pass before submitting
Follow existing code formatting and structure
Add appropriate error handling and logging

Testing Requirements

Unit tests for new functionality
Integration tests with mock EspoCRM responses
Manual testing with real EspoCRM instances
Documentation updates for new features

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Issues: GitHub Issues
Documentation: Check the docs/ directory for additional documentation
EspoCRM API: Official EspoCRM API Documentation
MCP Specification: Model Context Protocol Documentation

Changelog

Version 2.0.0 - AI Chatbot Integration 🤖

Complete Chatbot Interface: Floating chat bubble that embeds in EspoCRM
Natural Language Processing: Chat in plain English to perform CRM operations
WebSocket Communication: Real-time bidirectional communication
47 MCP Tools Access: Full CRM functionality via conversational interface
Security & Rate Limiting: Production-ready security with input validation
Docker Deployment: Containerized chatbot server alongside MCP server
Mobile Responsive: Beautiful interface that works on all devices
EspoCRM Integration: Simple 3-line integration with existing EspoCRM instances
AI-Powered: Optional OpenAI integration for advanced natural language understanding
Production Testing: Comprehensive test suite and demo interface

Version 1.5.0 - Phase 3 Complete Communication & Relationship Management

Relationship Management: 3 new tools for linking/unlinking entities and managing relationships
Communication Tools: 7 new tools for calls, cases, notes, and document management
Entity Relationship Operations: Link/unlink any entities, get relationship details
Call Management: Create and search call records with duration and direction tracking
Case Management: Create and search support cases with priority and type categorization
Note System: Add notes to any entity with internal/external visibility control
Document Management: Create document records with file attachment support
Advanced Formatting: Added specialized formatting for calls, cases, and notes
Tool Count: Expanded from 39 to 47 comprehensive tools (+8 new tools)

Version 1.4.0 - Phase 2 Complete Enterprise Solution

Team & Role Management: 7 new tools for complete user/team/role administration
Generic Entity Operations: 5 new tools for manipulating any EspoCRM entity (including custom entities)
Team Administration: Add/remove users from teams, assign positions, get team members
Role Assignment: Assign roles to users and get effective permissions
Universal Entity Support: Create, read, update, delete, and search any entity type
Custom Entity Support: Full support for custom EspoCRM entities and fields
Enhanced Type Safety: Added Team, Role, and GenericEntity TypeScript interfaces
Tool Count: Expanded from 27 to 39 comprehensive tools (+12 new tools)

Version 1.3.0 - Phase 1 Expansion

Task Management: Complete task lifecycle with 5 new tools (create, search, get, update, assign)
Lead Management: Full lead pipeline with 5 new tools (create, search, update, convert, assign)
Parent Relationships: Tasks can be linked to Leads, Accounts, Contacts, or Opportunities
Lead Conversion: Convert leads to contacts, accounts, and opportunities in one operation
Advanced Task Features: Priority levels, due dates, status tracking, and user assignment
Expanded Search: Task and lead search with comprehensive filtering options
Type Safety: Enhanced TypeScript interfaces for all new entities
Tool Count: Expanded from 17 to 27 comprehensive tools

Version 1.2.0

Enhanced Meeting Management: Complete CRUD operations for meetings
User Management: Search and lookup functionality for users
Advanced Date Filtering: Date range support for all search operations
Calendar Sync Compatibility: Google Calendar integration support
Improved Error Handling: Better error messages and debugging
Connection Fix: Resolved API endpoint compatibility issues

Version 1.1.0

Extended Entity Support: Added comprehensive type definitions
Enhanced Search: Advanced filtering capabilities
Performance Improvements: Optimized API client and error handling

Version 1.0.0

Initial release with full MCP 2024/2025 support
Complete CRUD operations for Contacts, Accounts, Opportunities
Docker support and comprehensive testing
Multiple authentication methods
Production-ready logging and error handling

Enterprise-grade EspoCRM integration for modern AI applications

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

Open source MCP server for EspoCRM

Related MCP Servers

salesforce-mcp
leilaabdel
-
security
F
license
-
quality
Salesforce MCP Server
Last updated -
Python
opengov-mcp-server
srobbin
A
security
A
license
A
quality
opengov-mcp-server
Last updated -
1
565
8
TypeScript
MIT License
MCP-openproject
jessebautista
-
security
F
license
-
quality
MCP-openproject
Last updated -
2
TypeScript
OPNsense MCP Server
floriangrousset
-
security
A
license
-
quality
OPNsense MCP Server
Last updated -
8
Python
AGPL 3.0

View all related MCP servers

EspoCRM MCP Server

Features

Core Capabilities

Authentication & Security

Calendar Integration

AI Chatbot Integration

Developer Experience

Quick Start

Prerequisites

Installation

AI Chatbot Quick Start

Deploy Chatbot Interface

Environment Configuration

Required Configuration

Available Tools

Contact Management

Account Management

Opportunity Management

Meeting Management

User Management

Task Management

Lead Management

Team & Role Management

Generic Entity Operations

Relationship Management

Communication Tools

System Tools

Enhanced Search Capabilities

Date Range Filtering

Meeting-Specific Filters

User-Specific Filters

Usage Examples

Task Management

Lead Management

Team & Role Management

Generic Entity Operations

Relationship Management

Communication Tools

AI Chatbot Usage

Meeting Management

User Management

Advanced Contact Search with Date Filtering

Calendar Integration Workflow

Testing

Automated Testing

Manual Testing Scripts

Connection Testing

Enhanced Tools Testing

Random Contact Generation

Development

Project Structure

Key Components

MCP Server (src/index.ts)

EspoCRM Client (src/espocrm/client.ts)

Entity Types (src/espocrm/types.ts)

Tool Registry (src/tools/index.ts)

Formatting Utilities (src/utils/formatting.ts)

Development Workflow

Docker Deployment

Build and Run with Docker

Docker Compose

Calendar Sync Integration

Google Calendar Sync Compatibility

Sync Prevention Features

Workflow Integration

Troubleshooting

Common Issues

Connection Failures

Authentication Issues

Meeting Creation Issues

User Search Issues

Debug Mode

Connection Diagnostics

API Reference

Tool Schemas

Contact Schema

Meeting Schema

User Schema

Task Schema

Lead Schema

MCP Server (`src/index.ts`)

EspoCRM Client (`src/espocrm/client.ts`)

Entity Types (`src/espocrm/types.ts`)

Tool Registry (`src/tools/index.ts`)

Formatting Utilities (`src/utils/formatting.ts`)