Crisp MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with the Crisp customer support platform. Use it with Claude Code or any MCP-compatible client to manage support conversations, send messages, and more.

Installation

git clone https://github.com/getlate-dev/crisp-mcp.git
cd crisp-mcp
npm install
npm run build

Getting Your Crisp API Credentials

You'll need to create a Crisp Marketplace plugin to get API credentials. Here's how:

Step 1: Access the Marketplace

1. Go to Crisp Marketplace
2. Click "Create a Plugin" (you need a Crisp account)

Step 2: Create Your Plugin

1. Fill in the basic plugin info:

   • Name: Something like "My MCP Integration" (only visible to you)
   • Description: "Personal MCP server integration"
   • Category: Select "Automation"
   • Privacy: Keep it private (unless you want to publish)

2. Click "Create Plugin"

Step 3: Get Your Credentials

After creating the plugin:

1. Go to your plugin's settings page
2. Navigate to the "Tokens" section
3. You'll find:
   • Plugin ID (this is your CRISP_IDENTIFIER)
   • Plugin Secret Key (this is your CRISP_KEY)

Step 4: Get Your Website ID

1. Go to your Crisp Dashboard
2. Click on Settings (gear icon)
3. Go to Website Settings
4. Your Website ID is in the URL: app.crisp.chat/website/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/
5. Or find it under Setup Instructions > Website ID

Step 5: Configure Plugin Permissions

Back in the Marketplace plugin settings, you need to enable the required scopes:

1. Go to your plugin's "Permissions" tab

2. Enable these scopes:

   • website:conversation:sessions - Read conversations
   • website:conversation:messages - Read/write messages
   • website:conversation:states - Change conversation states
   • website:conversation:routing - Assign conversations
   • website:conversation:metas - Read/write metadata
   • website:operators:list - List team members
   • website:visitors:list - List visitors

3. Click "Save"

Step 6: Install Plugin on Your Website

1. Go to the "Installations" tab in your plugin settings
2. Click "Add Installation"
3. Select your website
4. Confirm the installation

You're now ready to use the MCP server!

Configuration

Set these environment variables:

Variable	Description	Example
CRISP_IDENTIFIER	Your plugin ID from Marketplace	ab1c2d3e-4f5g-6h7i-8j9k-0l1m2n3o4p5q
CRISP_KEY	Your plugin secret key	a1b2c3d4e5f6... (long string)
CRISP_WEBSITE_ID	Your website ID	12345678-1234-1234-1234-123456789012

Usage with Claude Code

Add this to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "crisp": {
      "command": "node",
      "args": ["/path/to/crisp-mcp/dist/index.js"],
      "env": {
        "CRISP_IDENTIFIER": "your-plugin-id",
        "CRISP_KEY": "your-plugin-secret-key",
        "CRISP_WEBSITE_ID": "your-website-id"
      }
    }
  }
}

Then restart Claude Code. You can now use natural language to manage your Crisp conversations:

• "Show me unresolved support tickets"
• "What's the context of conversation session_abc123?"
• "Reply to that customer saying we're looking into it"
• "Mark that conversation as resolved"

Available Tools

Conversation Management

Tool	Description
list_conversations	List conversations with optional filtering (page, search, unresolved, unread)
get_unresolved_conversations	Get all unresolved conversations (paginated)
get_conversation	Get detailed info about a specific conversation
search_conversations	Search conversations by text query

Messages

Tool	Description
get_messages	Get messages from a conversation
get_conversation_with_messages	Get conversation and messages formatted for analysis
send_message	Send a message (text or internal note) to a conversation

Conversation State

Tool	Description
set_conversation_state	Change state (pending, unresolved, resolved)
update_conversation_meta	Update metadata (email, nickname, subject, segments)
add_segments	Add tags/segments to a conversation
remove_segments	Remove tags/segments from a conversation

Conversation Actions

Tool	Description
assign_conversation	Assign to a specific operator
block_conversation	Block a conversation
unblock_conversation	Unblock a conversation
delete_conversation	Permanently delete a conversation

Team & Visitors

Tool	Description
get_operators	Get list of support team operators
get_visitors	Get list of current website visitors

Available Resources

URI	Description
crisp://conversations/unresolved	List of all unresolved support conversations

Examples

List unresolved conversations

Use the list_conversations tool with unresolved_only: true

Get a support ticket with full context

Use the get_conversation_with_messages tool with the session_id

Reply to a customer

Use the send_message tool with session_id and content

Add an internal note (not visible to customer)

Use the send_message tool with type: "note"

Mark a ticket as resolved

Use the set_conversation_state tool with state: "resolved"

Development

# Watch mode for development
npm run dev

# Build for production
npm run build

# Run the server directly
npm start

Troubleshooting

"Crisp API error: 401 Unauthorized"

• Check that your CRISP_IDENTIFIER and CRISP_KEY are correct
• Make sure you've installed the plugin on your website

"Crisp API error: 403 Forbidden"

• Your plugin may be missing required permissions
• Go to Marketplace > Your Plugin > Permissions and enable the necessary scopes

"Website not found"

• Double-check your CRISP_WEBSITE_ID
• Make sure the plugin is installed on that specific website

License

MIT