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

Related MCP server: mysql-mcp-server

🚀 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",
        "MYSQL_USER": "perfex_readonly",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "perfex_crm"
      }
    }
  }
}

For local installation:

{
  "mcpServers": {
    "mcp-perfex-crm": {
      "command": "node",
      "args": ["/path/to/mcp-perfex-crm/dist/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "perfex_readonly",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "perfex_crm"
      }
    }
  }
}

📖 Usage

Example: List Customers

// Via MCP
const result = await use_mcp_tool({
  server_name: "mcp-perfex-crm",
  tool_name: "get_customers",
  arguments: {
    limit: 10,
    active: true
  }
});

Example: Create Project

const result = await use_mcp_tool({
  server_name: "mcp-perfex-crm",
  tool_name: "create_project",
  arguments: {
    name: "New Website",
    client_id: 123,
    start_date: "2025-02-01",
    billing_type: "fixed_rate",
    project_cost: 5000
  }
});

🧪 Development

# Development mode with hot reload
npm run dev

# Run linter
npm run lint

# Format code
npm run format

# Run tests with coverage
npm run test:coverage

# Production build
npm run build

📊 Code Quality

• ✅ TypeScript: Robust type system

• ✅ ESLint: Zero warnings, strict configuration

• ✅ Prettier: Consistent formatting

• ✅ Jest: Configured testing framework

• ✅ GitHub Actions: Automated CI/CD

• ✅ Optimized Logging: Production configuration with minimal context impact

🔒 Security

• All queries use prepared statements

• Input validation on all tools

• Read-only connections by default

• Audit logs for sensitive operations

• Masks for sensitive data in logs

🤝 Contributing

Contributions are welcome! Please:

1. Fork the project

2. Create a feature branch (git checkout -b feature/AmazingFeature)

3. Commit your changes (git commit -m 'Add some AmazingFeature')

4. Push to the branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

Code Standards

• Follow the configured TypeScript/ESLint style

• Add tests for new functionality

• Keep documentation updated

• Zero warnings is mandatory

📈 Roadmap

v1.0.1 (February 2025)

• Enhanced error handling

• Performance metrics dashboard

• Automated documentation generation

• Extended test coverage

v1.1.0 (Q1 2025)

• Test coverage >80%

• Complete TypeScript strict mode

• Webhook support

• Intelligent caching

v1.2.0 (Q2 2025)

• Analytics dashboard

• Batch operations

• GraphQL gateway

• Enhanced multi-tenant support

📝 Documentation

• API Reference - Complete API documentation

• Type System - Type system guide

• CI/CD Setup - Pipeline configuration

• Contributing - Contribution guide

📄 License

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

👨‍💻 Author

Emanuel Almeida

• GitHub: @YOUR_USERNAME

• LinkedIn: Emanuel Almeida

• Email: your.email@example.com

🙏 Acknowledgments

• Anthropic team for the Model Context Protocol

• Perfex CRM community

• All contributors

📊 Performance Benchmarks

🏗️ Architecture

mcp-perfex-crm/
├── src/
│   ├── modules/          # Business logic modules
│   ├── tools/            # MCP tools implementation
│   ├── types/            # TypeScript definitions
│   ├── utils/            # Utility functions
│   └── connections/      # Database connections
├── tests/                # Test suites
├── docs/                 # Documentation
└── examples/             # Usage examples

⭐ If this project helped you, please consider giving it a star!

🚀 Ready to supercharge your Perfex CRM integration? Get started now!