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```bash
git clone https://github.com/mrsnailo/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`):```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```bash
# 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_IDENTIFIERandCRISP_KEYare 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
