espocrm-mcp-server

EspoCRM MCP Server

A Model Context Protocol (MCP) server designed to interact with the EspoCRM API.

This server allows language models and other MCP clients to perform common CRUD (Create, Read, Update, Delete) operations and search actions within an EspoCRM instance.

Features

This server provides the following tools:

• get_record: Fetches details of a specific EspoCRM record by its type (e.g., Contact, Account) and ID.
• create_record: Creates a new record in EspoCRM (e.g., a new Lead).
• update_record: Updates an existing record in EspoCRM.
• delete_record: Deletes a record from EspoCRM.
• search_records: Searches for EspoCRM records based on specified criteria using EspoCRM's search parameters.
• get_related_records: Retrieves records linked to a specific EspoCRM record via a defined relationship (e.g., contacts for an Account).

Configuration

Required Configuration

This server requires two pieces of information to connect to your EspoCRM instance:

• Site URL: The full base URL of your EspoCRM instance (e.g., https://mycrm.example.com).
• API Key: An API key generated from your EspoCRM instance.

These can be provided as command-line arguments or environment variables (see Configuration Methods below).

Optional Configuration

Additionally, you can configure:

• SSL Verification: Disable SSL certificate verification for environments with self-signed certificates or development setups.
• API Timeout: Set a custom timeout for API requests (default: 15000ms).

Configuration Methods

All settings can be configured using either command-line arguments or environment variables:

Setting	Command-line Arg (position)	Environment Variable	Default
Site URL	1st argument	ESPOCRM_SITE_URL	(Required)
API Key	2nd argument	ESPOCRM_API_KEY	(Required)
Ignore SSL	3rd argument: ignore-ssl	ESPOCRM_IGNORE_SSL=true	false
API Timeout	N/A	ESPOCRM_API_TIMEOUT	15000 (ms)

Command-line arguments take precedence over environment variables.

Generating an API Key

• Log in to your EspoCRM instance as an administrator.
• Navigate to Administration > API Users.
• Click Create API User.
• Give it a descriptive name (e.g., "MCP Integration").
• Select API Key as the Authentication Method.
• Assign a Role that grants the necessary permissions for the tools (read, create, update, delete access to relevant entities like Contacts, Accounts, Leads, etc.). You might need to create a specific role if a suitable one doesn't exist.
• Save the user.
• Copy the generated API Key.

Installation / Running

Option 1: Using npx (After Publishing to npm)

Once the package is published to npm (e.g., as espocrm-mcp-server or @your-scope/espocrm-mcp-server), you can configure your MCP client to run it using npx.

Add the following to your MCP settings file (adjust paths/names as needed):

• VS Code Extension (macOS): ~/Library/Application Support/Code - Insiders/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Claude Desktop App (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• (Adapt paths for other operating systems)

{
  "mcpServers": {
    // ... other servers
    "espocrm": {
      "command": "npx",
      "args": [
        "espocrm-mcp-server", // Or your scoped package name @your-scope/espocrm-mcp-server
        "YOUR_ESPOCRM_SITE_URL", // Arg 1: Site URL
        "YOUR_ESPOCRM_API_KEY",  // Arg 2: API Key
        "ignore-ssl"             // Arg 3: Optional - disable SSL verification
      ],
      "env": {
        "ESPOCRM_SITE_URL": "YOUR_ESPOCRM_SITE_URL", // Alternative to args[0]
        "ESPOCRM_API_KEY": "YOUR_ESPOCRM_API_KEY",   // Alternative to args[1]
        "ESPOCRM_IGNORE_SSL": "true",                // Alternative to args[2]
        "ESPOCRM_API_TIMEOUT": "30000"               // Custom timeout in ms (30s)
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Important:

• Replace espocrm-mcp-server with your actual published package name if different.
• Replace placeholder values with your actual credentials.
• You can use either command-line args or environment variables, or a combination of both (args take precedence).
• The third argument ignore-ssl and its environment variable counterpart ESPOCRM_IGNORE_SSL=true will disable SSL certificate verification. This is useful when working with self-signed certificates or local development environments.

Option 2: Running Locally with Node

If you haven't published the package, you can run it directly using Node.

{
  "mcpServers": {
    // ... other servers
    "espocrm": {
      "command": "node",
      "args": [
        "/path/to/espocrm-server/build/index.js", // <-- Update this path
        "YOUR_ESPOCRM_SITE_URL",                 // Arg 1: Site URL
        "YOUR_ESPOCRM_API_KEY",                   // Arg 2: API Key
        "ignore-ssl"                              // Arg 3: Optional - disable SSL verification
      ],
      "env": {
        "ESPOCRM_API_TIMEOUT": "30000"            // Custom API timeout (30s)
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Option 3: Using Docker

If using Docker, you can set environment variables with the -e flag:

docker run -i --rm \
  -e ESPOCRM_SITE_URL=https://your-crm.example.com \
  -e ESPOCRM_API_KEY=your_api_key_here \
  -e ESPOCRM_IGNORE_SSL=true \
  -e ESPOCRM_API_TIMEOUT=30000 \
  espocrm-mcp-server

Alternatively, use command-line arguments:

docker run -i --rm espocrm-mcp-server https://your-crm.example.com your_api_key_here ignore-ssl

SSL Certificate Errors

If you encounter errors like:

MCP error -32603: EspoCRM API Error: unable to get local issuer certificate (Status: undefined)

This indicates an SSL certificate validation issue. This commonly happens with:

• Self-signed certificates
• Development environments
• Corporate proxies with SSL inspection

To fix this, you can disable SSL verification in one of these ways:

• Add ignore-ssl as the third command-line argument
• Set the environment variable ESPOCRM_IGNORE_SSL=true

Security Note: Only disable SSL verification in trusted or development environments. In production, always use proper SSL certificates and keep verification enabled.

Usage

Once configured and running, you can invoke the tools using the server name espocrm.

Example:

"Use the espocrm server to get the Contact record with ID 6abcdef1234567890."

<use_mcp_tool>
  <server_name>espocrm</server_name>
  <tool_name>get_record</tool_name>
  <arguments>
  {
    "entityType": "Contact",
    "id": "6abcdef1234567890"
  }
  </arguments>
</use_mcp_tool>

Development

This server is built with TypeScript.

Install dependencies:

npm install

Build the server (compiles TypeScript to JavaScript in build/):

npm run build

For development with auto-rebuild on file changes:

npm run watch

Docker Usage

This project includes a Dockerfile for running the server in a container.

1. Build the Image:

Navigate to the espocrm-server directory in your terminal and run:

docker build -t espocrm-mcp-server .

(You can replace espocrm-mcp-server with your preferred image tag)

2. Run the Container:

Run the container, passing the Site URL and API Key as command-line arguments after the image name. Since MCP uses standard input/output for communication, you need to run it interactively (-i).

docker run -i --rm espocrm-mcp-server YOUR_ESPOCRM_SITE_URL YOUR_ESPOCRM_API_KEY

Replace YOUR_ESPOCRM_SITE_URL and YOUR_ESPOCRM_API_KEY with your actual credentials. The --rm flag automatically removes the container when it exits.

(Note: Integrating a Dockerized MCP server with clients like the VS Code extension might require custom configuration or wrapper scripts, as the client typically expects to launch a local process directly.)

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser, allowing you to see requests and responses flowing through the server.

License

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