Kayzen Analytics

A Model Context Protocol (MCP) server implementation for interacting with Kayzen Analytics API. This package enables AI models to access and analyze Kayzen advertising campaign data through a standardized interface.

Features

• Automated Authentication: Built-in token management with automatic refresh mechanism
• Report Management: Easy access to Kayzen analytics reports
• Error Handling: Comprehensive error handling for API interactions
• TypeScript Support: Full TypeScript implementation with type definitions
• Environment Based Configuration: Simple setup using environment variables

Installation

npm install @feedmob-ai/kayzen-mcp

Configuration

Create a .env file with your Kayzen credentials:

KAYZEN_USERNAME=your_username
KAYZEN_PASSWORD=your_password
KAYZEN_BASIC_AUTH=your_basic_auth_token
KAYZEN_BASE_URL=https://api.kayzen.io/v1  # Optional, defaults to this value

Usage

Basic Setup

import { KayzenMCPServer } from '@feedmob-ai/kayzen-mcp';

const server = new KayzenMCPServer();
server.start();

Available Tools

1. list_reports

Lists all available reports from Kayzen Analytics.

• Inputs: None
• Returns: Array of report objects containing:
  • id: Report identifier
  • name: Report name
  • type: Report type

const reports = await server.tools.list_reports();

2. get_report_results

Retrieves results for a specific report.

• Inputs:
  • report_id (string, required): ID of the report to fetch
  • start_date (string, optional): Start date in YYYY-MM-DD format
  • end_date (string, optional): End date in YYYY-MM-DD format
• Returns: Report data and metadata

const results = await server.tools.get_report_results({
  report_id: 'report_id',
  start_date: '2024-01-01',  // optional
  end_date: '2024-01-31'     // optional
});

3. analyze_report_results (Prompt)

Analyzes report results and provides insights.

• Inputs:
  • report_id (string): ID of the report to analyze
• Analysis includes:
  • Performance metrics
  • Key trends
  • Areas for optimization
  • Unusual patterns or anomalies

Setup

Usage with Claude Desktop

To use this with Claude Desktop, add the following to your claude_desktop_config.json:

NPX

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@feedmob-ai/kayzen-mcp"
      ],
      "env": {
        "KAYZEN_USERNAME": "username",
        "KAYZEN_PASSWORD": "pasword",
        "KAYZEN_BASIC_AUTH": "auth token"
      }
    }
  }
}

Development

Prerequisites

• Node.js (v16 or higher)
• npm (v7 or higher)
• Kayzen API credentials

Scripts

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

# Development mode with hot-reload
npm run dev

Project Structure

kayzen-mcp/
├── src/
│   ├── server.ts        # MCP server implementation
│   └── kayzen-client.ts # Kayzen API client
├── dist/               # Compiled JavaScript
└── package.json       # Project configuration

Dependencies

Main dependencies:

• @modelcontextprotocol/sdk: ^1.7.0
• axios: ^1.8.3
• dotenv: ^16.4.7
• zod: ^3.24.2

Error Handling

The server handles various error scenarios:

• Authentication failures
• Invalid API requests
• Network issues
• Token expiration and refresh
• Invalid parameters

License

MIT License

Author

FeedMob