kayako-mcp-server 0.1.0

MCP server for interacting with Kayako API

Kayako MCP Server

A Model Context Protocol (MCP) server for interacting with the Kayako API. This server provides tools to fetch Kayako tickets including all posts and conversation history.

Features

• fetch_ticket - Fetch a Kayako ticket by ID with all posts and conversation history
• Configurable output format (JSON or Markdown via environment variable)
• Automatic pagination for posts
• Session-based authentication with CSRF token support
• Filters out "Placing on hold" automated posts for cleaner output

Prerequisites

• Python 3.10 or higher
• Kayako account with API access
• Valid Kayako credentials (email and password)

Installation

1. Clone or navigate to this directory:

cd kayakoMCP

2. Install dependencies:

pip install -r requirements.txt

3. Create a .env file in the project root with your Kayako credentials:

KAYAKO_BASE_URL=https://your-domain.kayako.com
KAYAKO_EMAIL=[e-mail]
KAYAKO_PASSWORD=your-password
OUTPUT_FORMAT=markdown

Configuration

Environment Variables

The server requires the following environment variables:

• KAYAKO_BASE_URL - Your Kayako instance URL (e.g., https://example.kayako.com)
• KAYAKO_EMAIL - Your Kayako account email
• KAYAKO_PASSWORD - Your Kayako account password
• OUTPUT_FORMAT - Output format for tickets: markdown (default) or json

MCP Client Configuration

To use this server with an MCP client (like Claude Desktop), add the following to your MCP settings file:

For Claude Desktop (Windows)

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "kayako": {
      "command": "python",
      "args": [
        "\\path\\to\\kayakoMCP\\kayako_mcp_server.py"
      ],
      "env": {
        "KAYAKO_BASE_URL": "https://your-domain.kayako.com",
        "KAYAKO_EMAIL": "[e-mail]",
        "KAYAKO_PASSWORD": "your-password",
        "OUTPUT_FORMAT": "markdown"
      }
    }
  }
}

For Claude Desktop (macOS/Linux)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/claude/claude_desktop_config.json (Linux):

{
  "mcpServers": {
    "kayako": {
      "command": "python3",
      "args": [
        "/path/to/kayakoMCP/kayako_mcp_server.py"
      ],
      "env": {
        "KAYAKO_BASE_URL": "https://your-domain.kayako.com",
        "KAYAKO_EMAIL": "[e-mail]",
        "KAYAKO_PASSWORD": "your-password",
        "OUTPUT_FORMAT": "markdown"
      }
    }
  }
}

Usage

Available Tools

fetch_ticket

Fetch a Kayako ticket by ID, including all posts and conversation history.

Parameters:

• ticket_id (string, required) - The ID of the Kayako ticket to fetch

Output Format:

The output format is configured via the OUTPUT_FORMAT environment variable:

• "markdown" - Returns markdown-formatted text (default)
• "json" - Returns structured JSON data

Example usage in Claude Desktop:

Can you fetch Kayako ticket 12345?

Response Format

JSON Format

Returns the complete ticket and posts data as structured JSON:

{
  "ticket": {
    "status": 200,
    "data": {
      "id": 12345,
      "subject": "Issue with login",
      "created_at": "2024-01-15T10:30:00Z",
      "state": "OPEN",
      "post_count": 5,
      ...
    }
  },
  "posts": {
    "status": 200,
    "data": [
      {
        "id": 67890,
        "subject": "Issue with login",
        "contents": "I cannot log in to my account...",
        "created_at": "2024-01-15T10:30:00Z",
        "is_requester": true,
        ...
      },
      ...
    ],
    "total_count": 5
  }
}

Markdown Format

Returns a human-readable markdown document:

# Ticket #12345: Issue with login

**State:** OPEN
**Created:** 2024-01-15T10:30:00Z
**Total Posts:** 5

---

## Original Ticket

**Subject:** Issue with login
**Date:** 2024-01-15T10:30:00Z
**Is Requester:** True

I cannot log in to my account...

---

## Conversation

### Post 1 - Agent (ID: 123)

**Date:** 2024-01-15T11:00:00Z
**Status:** ACTIVE

Thank you for contacting us...

---

Testing

You can test the server directly from the command line:

python kayako_mcp_server.py

Then send MCP protocol messages via stdin, or use an MCP inspector tool.

Authentication

The server uses Kayako's Basic Authentication to obtain a session token:

1. Encodes credentials as Base64
2. Makes a request to /api/v1/me.json
3. Extracts session_id, requester_id, and X-CSRF-Token
4. Caches authentication for subsequent requests
5. Uses session-based authentication for all API calls

Error Handling

The server handles various error conditions:

• Missing environment variables
• Authentication failures (403, invalid credentials)
• Two-factor authentication requirements (not supported)
• Expired passwords
• Network errors
• Invalid or non-existent ticket IDs
• API errors

All errors are returned as descriptive error messages to help with troubleshooting.

Security Notes

• The server caches authentication tokens for the duration of the session
• Uses HTTPS for all API communications

Limitations

• Two-factor authentication is not currently supported
• Only supports session-based authentication (not API keys)
• Requires valid Kayako user account credentials

Troubleshooting

Authentication fails with 403

• Check that your credentials are correct
• Ensure two-factor authentication is disabled for the account
• Verify your password hasn't expired

Ticket not found

• Verify the ticket ID exists in your Kayako instance
• Ensure your account has permission to view the ticket

Connection errors

• Check that KAYAKO_BASE_URL is correct and accessible
• Verify your network connection
• Check if there are any firewall restrictions

Contributing

This server follows MCP best practices:

• Uses the official mcp Python SDK
• Implements proper tool schemas with descriptions
• Handles errors gracefully
• Returns structured data that's easy to consume
• Supports multiple output formats for flexibility

License

MIT License