kayako-mcp-server 0.1.0
MCP server for interacting with Kayako API
License: MIT
Requires Python: >=3.10
Keywords: mcp, kayako, api, model-context-protocol

# 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:

```bash
cd kayakoMCP
```

2. Install dependencies:

```bash
pip install -r requirements.txt
```

3. Create a `.env` file in the project root with your Kayako credentials:

```env
KAYAKO_BASE_URL=https://your-domain.kayako.com
KAYAKO_EMAIL=your-email@example.com
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`:

```json
{
  "mcpServers": {
    "kayako": {
      "command": "python",
      "args": [
        "\\path\\to\\kayakoMCP\\kayako_mcp_server.py"
      ],
      "env": {
        "KAYAKO_BASE_URL": "https://your-domain.kayako.com",
        "KAYAKO_EMAIL": "your-email@example.com",
        "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):

```json
{
  "mcpServers": {
    "kayako": {
      "command": "python3",
      "args": [
        "/path/to/kayakoMCP/kayako_mcp_server.py"
      ],
      "env": {
        "KAYAKO_BASE_URL": "https://your-domain.kayako.com",
        "KAYAKO_EMAIL": "your-email@example.com",
        "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:

```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:

```markdown
# 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:

```bash
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