Crisp

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/zernio-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 Discovery

Tool	Description
list_conversations	Paginated list with filters: search, segment, unresolved_only, unread_only, assigned_to, unassigned_only, mention_only, order_by_waiting. Returns { conversations, page_number, has_more, next_page }.
get_unresolved_conversations	All unresolved across multiple pages (flat array).
conversations_awaiting_reply	Best triage tool. Unresolved AND customer is waiting on an operator reply. Sorted longest-wait first.
conversations_assigned_to_me	Conversations assigned to a specific operator (pass user_id).
conversations_by_segment	Conversations tagged with a specific segment (e.g. refund, bug).
search_conversations	Plain-text search.

Conversation Detail

Tool	Description
get_conversation	Detailed info about a specific conversation.
get_messages	Message history. File/image/audio messages have their URLs surfaced cleanly.
get_conversation_with_messages	Plain-text formatted transcript for analysis (small context).
get_rich_context	Heavy context: conversation + messages + Crisp People profile + past conversations from same customer + custom data, all in one call. Replaces 4-5 round trips.

Messaging

Tool	Description
send_message	Send text or internal note. Supports mentions for @-tagging operators.
send_file_message	Attach a file by URL (no upload needed — pass any publicly hosted URL).

Conversation State

Tool	Description
set_conversation_state	Change state (pending, unresolved, resolved).
update_conversation_meta	Update metadata (email, nickname, subject, segments).
add_segments / remove_segments	Add or remove tags.

Conversation Actions

Tool	Description
assign_conversation	Assign to a specific operator (by user_id).
resolve_conversation / reopen_conversation	One-shot aliases over set_conversation_state.
block_conversation / unblock_conversation	Block/unblock a conversation.
delete_conversation	Permanently delete.

Realtime & Navigation

Tool	Description
set_composing_state	Send a "typing…" indicator to the customer (start/stop). Auto-expires after ~6s.
mark_messages_read	Mark operator-side unread counter as read so conversations stop resurfacing in triage.
get_conversation_url	Build the Crisp web app URL for a conversation — useful for Slack/Linear escalations.

People / Contacts

Tool	Description
find_person_by_email	Find a Crisp People profile by email. Returns null if no match.
find_conversations_for_email	Shortcut: resolve person + list their conversations in one call.
get_person	Full profile by people_id.
get_person_conversations	All conversations this person has ever had.
get_person_data	Custom data dictionary (plan, subscription, etc. pushed in by your app).

Team & Visitors

Tool	Description
get_operators	Typed list of operators (user_id, email, role, availability).
find_operator_by_email	Resolve an operator's user_id from their email (useful before assign_conversation).
get_visitors	Active website visitors with geolocation + page context.

Reliability

The HTTP client automatically retries with exponential backoff on 429 (rate limited) and 5xx responses, honouring Retry-After headers when present. Up to 4 retries by default. Prevents silent drops of operator replies when Crisp is under load.

Available Resources

URI	Description
crisp://conversations/awaiting-reply	Unresolved conversations where the customer is currently waiting on an operator reply (longest-wait first).
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