MCP Perfex CRM - High-Performance MCP Server for Perfex CRM

🎯 Overview

MCP Perfex CRM is a high-performance Model Context Protocol (MCP) server that provides direct and optimized access to Perfex CRM's MySQL database. This project offers a high-performance alternative to traditional REST APIs, with focus on code quality, security, and maintainability.

✅ Current Status - v1.0.0-stable

• 14 functional modules with 186+ tested tools covering comprehensive Perfex CRM functionality
• Zero warnings in ESLint and TypeScript
• Complete CI/CD with GitHub Actions
• Robust type system implemented
• Complete API documentation

🚀 Features

• 🔥 Performance: Direct MySQL access, 10-100x faster than REST API
• 🛡️ Security: Prepared statements, input validation, read-only connections
• 📊 Modular: Extensible architecture with independent modules
• 🧪 Tested: Jest testing framework with growing coverage
• 📝 Documented: Complete API documentation with examples
• 🔄 CI/CD: Automated pipeline with quality gates

📦 Available Modules

Core (100% Functional)

• Customers - Complete customer management
• Estimates - Estimates and proposals
• Invoices - Complete invoice management with payments and statistics (8 tools)
• Leads - Lead management, conversion, and lifecycle tracking (9 tools)
• Projects - Project management
• Tasks - Task control
• Contracts - Contract management
• Payments - Payment processing
• Expenses - Expense control
• Tickets - Complete support system with delete/export tools

Reporting

• Financial Reporting - Advanced financial reports
• Resource Management - Resource management
• Timesheets - Time tracking

Utilities

• Subscriptions - Subscription management
• Credit Notes - Credit notes

🛠️ Installation

Option 1: NPM Installation (Recommended)

npm install -g mcp-perfex-crm

Option 2: Local Installation

# Clone repository
git clone https://github.com/YOUR_USERNAME/mcp-perfex-crm
cd mcp-perfex-crm

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your MySQL settings

# Compile project
npm run build

# Run tests
npm test

⚙️ Configuration

1. Database Configuration

# .env
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=perfex_readonly
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=perfex_crm

# Log optimization for production
LOG_LEVEL=error
NODE_ENV=production
ENABLE_AUDIT_LOG=false

2. N8N Integration

MCP Perfex CRM is fully compatible with N8N for workflow automation:

# Install as N8N tool
npm install -g mcp-perfex-crm

# Or use in N8N Docker
FROM n8nio/n8n:latest
RUN npm install -g mcp-perfex-crm

N8N Workflow Example:

{
  "nodes": [
    {
      "parameters": {
        "command": "mcp-perfex-crm",
        "options": {
          "env": {
            "MYSQL_HOST": "your-db-host",
            "MYSQL_USER": "readonly_user",
            "MYSQL_PASSWORD": "secure_password",
            "MYSQL_DATABASE": "perfex_crm"
          }
        }
      },
      "type": "@n8n/n8n-nodes-langchain.toolWorkflow",
      "position": [250, 300],
      "id": "perfex-crm-tool"
    }
  ]
}

3. Claude Desktop Integration

{
  "mcpServers": {
    "mcp-perfex-crm": {
      "command": "mcp-perfex-crm",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "

... [View full README on GitHub](https://github.com/Descomplicar-Marketing-e-Tecnologia/mcp-perfex-crm#readme)