Kayzen Analytics

🚀 Kayzen Analytics MCP Server

A Model Context Protocol (MCP) server implementation that interacts with the Kayzen Analytics API. This package allows AI models to access and analyze Kayzen advertising campaign data through a standard interface.

🚀 Quick Start

The Kayzen Analytics MCP Server enables seamless interaction with the Kayzen Analytics API. It provides a set of tools for AI models to access and analyze advertising campaign data.

✨ Features

• Automated Authentication: Built - in token management with an automatic refresh mechanism.
• Report Management: Effortlessly access 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 and enter 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, default value

💻 Usage Examples

Basic Usage

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

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

Tool Usage

1. list_reports

List all available reports in Kayzen Analytics.

• Input: None
• Return: An 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

Get the results of a specific report.

• Input:
  • report_id (string, required): The ID of the report to retrieve.
  • start_date (string, optional): Start date in YYYY - MM - DD format.
  • end_date (string, optional): End date in YYYY - MM - DD format.
• Return: 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 (Hint)

Analyze report results and provide insights.

• Input:
  • report_id (string): The ID of the report to analyze.
• Analysis includes:
  • Performance metrics
  • Key trends
  • Areas for optimization
  • Anomalous patterns or exceptions

🛠️ Setup

Usage with Claude Desktop

To use with Claude Desktop, add the following to 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": "Authentication 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 - reloading)
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
• Automatic token refresh