kayzen-mcp

# Kayzen Analytics MCP Server 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 ```bash npm install @feedmob-ai/kayzen-mcp ``` ## Configuration Create a `.env` file with your Kayzen credentials: ```bash 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 ```typescript 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 ```typescript 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 ```typescript 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 ```json { "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 ```bash # 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