@mixio-pro/kalaasetu-mcp/README.md

A powerful Model Context Protocol server providing AI tools for content generation and analysis

# kalaasetu-mcp

Kalaasetu MCP Server - A powerful Model Context Protocol server providing various AI tools for content generation and analysis.

## Quick Start

```bash
npx @mixio-pro/kalaasetu-mcp@latest
```

## Features

### 🎨 Gemini Tools
- **Text to Image**: Generate images from text prompts
- **Image Editing**: Edit existing images with AI
- **Image Analysis**: Analyze and describe images
- **Text-to-Speech**: Generate natural speech from text
- **Video Analysis**: Analyze video content

### 📹 Video Tools
- **Image-to-Video** (Vertex AI Veo): Generate videos from images using Google's Veo models
- **Infinitalk** (FAL AI): Create talking avatar videos with lip-sync from image and audio

### 🎬 YouTube Tools
- **YouTube Analyzer**: Analyze YouTube videos and extract insights

### 🔍 Perplexity Search Tools
- **Image Search**: Search for images using Perplexity AI with domain and format filters
- **Video Search**: Search for videos using Perplexity AI with domain filters

## Installation

### Using npx (Recommended)

Run directly without installation:

```bash
npx @mixio-pro/kalaasetu-mcp@latest
```

### Global Installation

```bash
npm install -g @mixio-pro/kalaasetu-mcp
kalaasetu-mcp
```

### Local Development

To install dependencies for local development:

```bash
bun install
```

## MCP Client Configuration

### Cursor IDE

Add to your Cursor settings (`~/.cursor/config.json` or via Settings → MCP):

```json
{
  "mcpServers": {
    "kalaasetu": {
      "command": "npx",
      "args": ["@mixio-pro/kalaasetu-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key",
        "FAL_KEY": "your-fal-api-key",
        "PERPLEXITY_API_KEY": "your-perplexity-api-key", 
        "STORAGE_PROVIDER":"gcs",
        "GCS_BUCKET":"your-gcs-bucket-name"
      }
    }
  }
}
```

### OpenCode IDE

Add to your OpenCode MCP configuration:

```json
{
  "mcpServers": {
    "kalaasetu": {
      "command": "npx",
      "args": ["@mixio-pro/kalaasetu-mcp@latest"],
      "environment": {
        "GEMINI_API_KEY": "your-gemini-api-key",
        "FAL_KEY": "your-fal-api-key",
        "PERPLEXITY_API_KEY": "your-perplexity-api-key", 
        "STORAGE_PROVIDER":"gcs",
        "GCS_BUCKET":"your-bucket-name"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "kalaasetu": {
      "command": "npx",
      "args": ["@mixio-pro/kalaasetu-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key",
        "FAL_KEY": "your-fal-api-key",
        "PERPLEXITY_API_KEY": "your-perplexity-api-key"
      }
    }
  }
}
```

### OpenCode IDE

Add to your OpenCode MCP configuration:

```json
{
  "mcpServers": {
    "kalaasetu": {
      "type": "local",
      "command": ["npx", "@mixio-pro/kalaasetu-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key",
        "FAL_KEY": "your-fal-api-key",
        "PERPLEXITY_API_KEY": "your-perplexity-api-key",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/gcp-credentials.json"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "kalaasetu": {
      "command": "npx",
      "args": ["@mixio-pro/kalaasetu-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key",
        "FAL_KEY": "your-fal-api-key",
        "PERPLEXITY_API_KEY": "your-perplexity-api-key",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/gcp-credentials.json"
      }
    }
  }
}
```

## Environment Variables

### Required API Keys

| Variable | Description | Get API Key |
|----------|-------------|-------------|
| `GEMINI_API_KEY` | For Gemini image generation, TTS, video analysis, and Veo video generation | [Google AI Studio](https://aistudio.google.com/app/apikey) |
| `FAL_KEY` | For Infinitalk and Hunyuan Avatar tools | [FAL AI](https://fal.ai/dashboard/keys) |
| `PERPLEXITY_API_KEY` | For image and video search | [Perplexity API](https://www.perplexity.ai/settings/api) |

### Setting Environment Variables

#### For Command Line Usage

```bash
# macOS/Linux
export GEMINI_API_KEY="your-gemini-api-key"
export FAL_KEY="your-fal-api-key"
export PERPLEXITY_API_KEY="your-perplexity-api-key"

# Windows (PowerShell)
$env:GEMINI_API_KEY="your-gemini-api-key"
$env:FAL_KEY="your-fal-api-key"
$env:PERPLEXITY_API_KEY="your-perplexity-api-key"
```

#### For MCP Clients

Set the environment variables in your MCP client configuration as shown in the examples above.

## Configuration

Set up the required API keys as environment variables:

```bash
# For Gemini and Vertex AI tools
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
export GEMINI_API_KEY="your-gemini-api-key"

# For FAL AI Infinitalk
export FAL_KEY="your-fal-api-key"

# For Perplexity Search Tools
export PERPLEXITY_API_KEY="your-perplexity-api-key"
```

## Running the Server

### Local Development

To run the server locally:

```bash
bun run src/index.ts
```

Or with auto-reload:

```bash
bun run dev
```

## Available Tools

### Infinitalk

Generate talking avatar videos from images and audio using FAL AI's Infinitalk model.

#### Parameters

- `image_url` (required): URL of the input image
- `audio_url` (required): URL of the audio file for lip-sync
- `prompt` (required): Text description guiding video generation
- `num_frames` (optional): Number of frames (41-721, default: 145)
- `resolution` (optional): Video resolution - "480p" or "720p" (default: "480p")
- `seed` (optional): Random seed for reproducibility (default: 42)
- `acceleration` (optional): Generation speed - "none", "regular", or "high" (default: "regular")

#### Example Usage

```json
{
  "image_url": "https://example.com/portrait.png",
  "audio_url": "https://example.com/speech.mp3",
  "prompt": "A person speaking professionally in a podcast setting",
  "resolution": "720p",
  "num_frames": 200
}
```

### Perplexity Images

Search for images using Perplexity AI with advanced filtering options.

#### Parameters

- `query` (required): The search query for images
- `image_domain_filter` (optional): Array of domains to include or exclude (prefix with '-' to exclude)
  - Example: `["wikimedia.org", "-gettyimages.com"]`
- `image_format_filter` (optional): Array of allowed image formats
  - Example: `["jpg", "png", "gif"]`

#### Example Usage

```json
{
  "query": "mountain landscapes",
  "image_domain_filter": ["wikimedia.org", "-gettyimages.com"],
  "image_format_filter": ["jpg", "png"]
}
```

### Perplexity Videos

Search for videos using Perplexity AI with domain filtering.

#### Parameters

- `query` (required): The search query for videos
- `search_domain_filter` (optional): Array of domains to limit search (use '-' prefix to exclude)
  - Example: `["youtube.com"]` or `["-tiktok.com"]`

#### Example Usage

```json
{
  "query": "yoga for beginners",
  "search_domain_filter": ["youtube.com"]
}
```

## Testing

You can test the MCP server using the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector npx @mixio-pro/kalaasetu-mcp@latest
```

## Requirements

- **Bun**: This package requires Bun runtime. Install from [bun.sh](https://bun.sh)
- **API Keys**: Obtain the necessary API keys from the providers listed above

## Project Info

This project was created using `bun init` in bun v1.3.1. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.