SuiteCRM_MCP

SuiteCRM MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with SuiteCRM's JSON API (v8), enabling AI assistants to interact with your SuiteCRM instance for lead management, contact operations, and CRM workflows.

Overview

This MCP server exposes SuiteCRM functionality through a standardized interface, allowing AI assistants like Claude to:

• Create, search, update, and manage leads
• Handle contact records and relationships
• Perform CRUD operations on CRM data
• Manage lead conversion workflows
• Execute complex CRM queries with filtering and pagination

Features

Lead Management

• ✅ Create new leads with validation
• ✅ Search leads with flexible criteria
• ✅ Update lead status and information
• ✅ Assign leads to team members
• ✅ Convert leads to accounts/contacts/opportunities
• ✅ Get lead status and source options

Contact Management

• ✅ Create and update contact records
• ✅ Search contacts with advanced filtering
• ✅ Link contacts to accounts
• ✅ Assign contacts to users
• ✅ View contact interaction history
• ✅ Duplicate and merge contact records

Core CRM Operations

• ✅ Full CRUD operations on all modules
• ✅ Relationship management between records
• ✅ Field metadata and validation
• ✅ Pagination and sorting support
• ✅ Authentication with OAuth 2.0

Prerequisites

• Node.js 18+ and npm
• SuiteCRM 8.x instance with JSON API enabled
• SuiteCRM API credentials (OAuth client)
• Claude Desktop or compatible MCP client

Installation

Option 1: NPM Package (Recommended)

npm install -g @modelcontextprotocol/server-suitecrm

Option 2: From Source

git clone <repository-url>
cd SuiteCRM_MCP
npm install
npm run build

Option 3: Docker

docker build -t suitecrm-mcp .
docker run -e SUITECRM_URL="your-url" \
           -e SUITECRM_USERNAME="your-username" \
           -e SUITECRM_PASSWORD="your-password" \
           -e SUITECRM_CLIENT_ID="your-client-id" \
           -e SUITECRM_CLIENT_SECRET="your-client-secret" \
           suitecrm-mcp

Setup

1. SuiteCRM Configuration

First, set up API access in your SuiteCRM instance:

1. Enable JSON API: Ensure SuiteCRM JSON API is enabled in Admin > System Settings
2. Create API User: Create a dedicated user account for MCP operations
3. Create OAuth Client:
   • Go to Admin > OAuth2 Clients and Servers
   • Create new OAuth2 Client
   • Note the Client ID and Client Secret
   • Set appropriate scopes and permissions

2. Environment Variables

Create a .env file or set environment variables:

SUITECRM_URL=https://your-suitecrm-instance.com/legacy
SUITECRM_USERNAME=your-api-username
SUITECRM_PASSWORD=your-api-password
SUITECRM_CLIENT_ID=your-oauth-client-id
SUITECRM_CLIENT_SECRET=your-oauth-client-secret

3. Claude Desktop Configuration

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "suitecrm": {
      "command": "mcp-server-suitecrm",
      "env": {
        "SUITECRM_URL": "https://your-suitecrm-instance.com/legacy",
        "SUITECRM_USERNAME": "your-api-username", 
        "SUITECRM_PASSWORD": "your-api-password",
        "SUITECRM_CLIENT_ID": "your-oauth-client-id",
        "SUITECRM_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "suitecrm": {
      "command": "node",
      "args": ["/path/to/SuiteCRM_MCP/dist/index.js"],
      "env": {
        "SUITECRM_URL": "https://your-suitecrm-instance.com/legacy",
        "SUITECRM_USERNAME": "your-api-username",
        "SUITECRM_PASSWORD": "your-api-password", 
        "SUITECRM_CLIENT_ID": "your-oauth-client-id",
        "SUITECRM_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

Usage Examples

Basic Lead Operations

Create a new lead:

Create a new lead for John Smith from Acme Corp with email john@acme.com and phone 555-1234

Search for leads:

Find all leads from companies containing "Tech" created in the last 30 days

Update lead status:

Update lead ID 12345 to "Qualified" status with note "Customer showed strong interest"

Convert a lead:

Convert lead ID 12345 to account, contact, and opportunity with name "Premium Package Deal"

Contact Management

Create a contact:

Create a new contact Sarah Johnson with email sarah@example.com, phone 555-9876, working at Tech Solutions Inc

Search contacts:

Find all contacts assigned to user Laurent Therond created this month

Link contact to account:

Link contact ID 67890 to account ID 12345

Advanced Queries

Complex lead search:

Search for leads with status "New" or "Assigned", from source "Web Form", created between 2024-01-01 and 2024-03-01, limit 50 results

Get relationship data:

Show me all email addresses and activities for contact ID 12345

Available Tools

Lead Tools

• create_lead - Create new lead records
• search_leads - Search leads with filters
• update_lead_status - Update lead status and notes
• assign_lead - Assign leads to users
• convert_lead - Convert leads to accounts/contacts/opportunities
• get_lead_status_options - Get valid status values
• get_lead_source_options - Get valid source values

Contact Tools

• create_contact - Create new contact records
• search_contacts - Search contacts with filters
• update_contact - Update contact information
• assign_contact - Assign contacts to users
• link_contact_to_account - Create contact-account relationships
• get_contact_by_id - Get detailed contact info
• delete_contact - Remove contact records
• duplicate_contact - Clone existing contacts

Generic CRM Tools

• get_available_modules - List all SuiteCRM modules
• get_entry_list - Get records from any module
• get_entry - Get specific record by ID
• set_entry - Create new records
• update_entry - Update existing records
• delete_entry - Delete records
• get_relationships - Get related records
• set_relationship - Create relationships
• get_module_fields - Get field definitions

User Management

The server includes predefined user assignments:

• Laurent Therond (user_id: 1)
• Nixon Goche (user_id: 27400e5c-545e-478a-bd04-67cb3e4f282f)
• Marina Goche (user_id: 35e41def-1b98-93bd-2488-656e42a819f3)

Use these IDs when assigning leads or contacts to team members.

Development

Building from Source

git clone <repository-url>
cd SuiteCRM_MCP
npm install
npm run build

Running Tests

npm test

Development Mode

npm run watch

API Reference

Authentication

The server automatically handles OAuth 2.0 authentication with SuiteCRM, including:

• Initial login with username/password
• Token refresh when needed
• Automatic re-authentication on token expiry

Error Handling

• Input validation using Zod schemas
• Comprehensive error logging
• Graceful fallbacks for API failures
• Detailed error messages for debugging

Pagination

Most list operations support pagination:

• page - Page number (1-based)
• page_size - Records per page (default: 20)
• limit - Alternative to page_size for some operations

Filtering

Advanced filtering with JSON API syntax:

{
  "operator": "and|or",
  "field_name": {
    "eq": "exact_value",
    "like": "%partial_value%", 
    "gt": "greater_than",
    "lt": "less_than"
  }
}

Troubleshooting

Common Issues

Authentication Failures:

• Verify SuiteCRM URL is correct and includes /legacy
• Check username/password are valid
• Ensure OAuth client is properly configured
• Verify API user has necessary permissions

Connection Errors:

• Confirm SuiteCRM instance is accessible
• Check firewall/network settings
• Verify SSL certificates if using HTTPS

Permission Errors:

• Ensure API user has appropriate module permissions
• Check OAuth client scopes
• Verify user roles and access controls

Debug Logging

Check the server log file at dist/server.log for detailed request/response information.

Environment Variables

Ensure all required environment variables are set:

echo $SUITECRM_URL
echo $SUITECRM_USERNAME  
echo $SUITECRM_CLIENT_ID
# (Don't echo sensitive values like password/secret)

Security Considerations

• Store credentials securely using environment variables
• Use dedicated API user accounts with minimal permissions
• Enable HTTPS for SuiteCRM API endpoints
• Regularly rotate OAuth client secrets
• Monitor API access logs
• Never commit credentials to version control

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Check the troubleshooting section above
• Review SuiteCRM API documentation
• Open an issue in the repository
• Consult MCP documentation at https://modelcontextprotocol.io

Changelog

v1.0.0

• Initial release
• Complete lead and contact management
• Full CRUD operations support
• OAuth 2.0 authentication
• Comprehensive tool set for CRM operations