EspoCRM MCP Server v1.8

Advanced Model Context Protocol (MCP) server for comprehensive EspoCRM integration and automation.

✨ Features & Capabilities

🔗 EspoCRM Integration

• Contact Management: Create, update, search contacts with full relationship mapping
• Activity Management: Tasks, meetings, calls with automated scheduling
• Email Operations: Send emails with SMTP integration and EspoCRM recording
• Calendar Functions: Meeting scheduling with timezone-aware datetime handling
• Data Operations: Universal search across all entities with advanced filtering

🤖 Automation Workflows

• Universal Contact Workflow: Complete contact creation + meeting scheduling + email notification
• Timezone-Safe Operations: Proper local time handling (no UTC conversion issues)
• Batch Operations: Bulk data management and cleanup utilities
• Error Prevention: Production-ready validation and error handling

🔒 Security & Configuration

• Environment Variables: All sensitive data stored in .env files
• No Hardcoded Data: Fully configurable via parameters and environment
• Secure SMTP: Encrypted email transmission with credential protection
• Production Ready: Comprehensive error handling and logging

🚀 Quick Start

1. Initial Setup

# Clone and install dependencies
npm install

# Copy configuration template
cp config.template.json config.json

2. Environment Configuration

Create .env file with your credentials:

# EspoCRM Configuration
ESPOCRM_URL=http://your-espocrm-instance.com
ESPOCRM_USERNAME=your_username
ESPOCRM_PASSWORD=your_password

# SMTP Configuration
SMTP_HOST=smtp.your-provider.com
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USER=your_email@domain.com
SMTP_PASS=your_email_password

# Email Templates
EMAIL_SENDER_NAME=Your Organization
MEETING_DESCRIPTION=Business meeting

3. EspoCRM Setup

# Auto-discover user IDs and configure EspoCRM
node setup_espocrm_ids.cjs

# Create email account in EspoCRM for sending
node create_email_account.cjs

# Run complete setup (combines above steps)
node complete_setup.cjs

🛠️ Core Tools & Usage

Universal Contact Workflow

Complete automation: contact creation + meeting + email notification

node universal_contact_workflow.cjs "John" "Doe" "john@company.com" 14 2
# Parameters: firstName lastName email [hour] [duration_hours]

Email Operations

# Send email with secure credentials
node secure_email_sender.cjs send "Meeting reminder for tomorrow"

# Test email configuration
node secure_email_sender.cjs test

# Professional email templates
node professional_email_template.cjs "recipient@email.com" "Subject" "Message body"

Calendar & Scheduling

# Calendar management with timezone handling
node final_calendar_solution.cjs

# Timezone-aware datetime corrections
node universal_timezone_corrector.cjs

Data Management

# Main MCP interface for all operations
node mcp.cjs --help

# Database cleanup and maintenance
node espocrm_cleanup.cjs

# Error prevention and validation
node production_error_prevention_framework.cjs

🏗️ Architecture & Components

DateTime Handling

• DateTimeHelper: Timezone-safe datetime formatting for EspoCRM
• Local Time Priority: Prevents UTC conversion errors
• Format: YYYY-MM-DD HH:MM:SS (EspoCRM compatible)

Email System

• Hybrid Approach: EspoCRM API recording + direct SMTP sending
• Template Engine: Configurable email templates via environment variables
• Status Tracking: Automatic email status updates in EspoCRM

Error Prevention

• Production Framework: Comprehensive validation and error handling
• Credential Security: Environment-based configuration
• API Compatibility: Support for various EspoCRM versions

🔐 Security Features

Credential Management

• Environment Variables: No hardcoded passwords or URLs
• Git Exclusion: .env files automatically excluded from version control
• Template System: Safe configuration templates without sensitive data

Data Protection

• Input Validation: All user inputs validated before processing
• SQL Injection Prevention: Parameterized queries and API calls
• Error Logging: Security-conscious error messages

Production Readiness

• Exception Handling: Graceful error recovery
• Connection Pooling: Efficient resource management
• Audit Logging: Comprehensive operation tracking

📋 Configuration Options

Environment Variables

Customization

• Email Templates: Customize via EMAIL_SUBJECT and EMAIL_BODY variables
• Meeting Defaults: Configure via MEETING_DESCRIPTION variable
• Timezone Settings: Automatic local timezone detection

🔧 Advanced Usage

Custom Workflows

Create your own automation scripts using the provided modules:

const UniversalContactWorkflow = require('./universal_contact_workflow.cjs');
const DateTimeHelper = require('./datetime_helper.cjs');

// Your custom automation logic

API Integration

All tools support programmatic usage:

const workflow = new UniversalContactWorkflow();
await workflow.executeWorkflow(firstName, lastName, email, hour, duration);

📦 Requirements

• Node.js: Version 18 or higher
• EspoCRM: Version 7.0+ (tested with various versions)
• SMTP Server: For email functionality
• Network Access: To EspoCRM instance and SMTP server

🔄 Build & Development

# Install dependencies
npm install

# Build TypeScript components
npm run build

# Run development server
npm run dev

# Run tests
npm test

🐛 Troubleshooting

Common Issues

1. Calendar 500 Errors: Run node final_calendar_solution.cjs
2. Timezone Problems: Use DateTimeHelper for all datetime operations
3. Email Not Sending: Verify SMTP credentials in .env
4. Connection Issues: Check EspoCRM URL and credentials

Debug Mode

Enable detailed logging by setting environment variable:

DEBUG=true node your_script.cjs

EspoCRM MCP Server v1.8 - Production-ready automation platform with enterprise-grade security and comprehensive EspoCRM integration.