# Kolosal Vision MCP

[![npm version](https://badge.fury.io/js/kolosal-vision-mcp.svg)](https://www.npmjs.com/package/kolosal-vision-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An MCP (Model Context Protocol) server that provides AI-powered image analysis and OCR using the [Kolosal Vision API](https://kolosal.ai). Seamlessly integrate vision capabilities into Claude Desktop, Cursor IDE, or any MCP-compatible client.

## ✨ Features

- **🖼️ Image Analysis** - Analyze images with natural language queries
- **🔗 URL Support** - Automatically downloads and processes images from URLs
- **📁 Local File Support** - Directly analyze images from your filesystem
- **📝 Base64 Support** - Accepts base64-encoded images
- **🎯 Structured Responses** - Returns organized analysis with key observations
- **🔄 Multiple Formats** - Supports JPEG, PNG, GIF, WebP, and BMP

## 📦 Installation

### Using npx (Recommended)

No installation needed! Just configure your MCP client to use:

```bash
npx kolosal-vision-mcp
```

### Global Installation

```bash
npm install -g kolosal-vision-mcp
```

### Local Installation

```bash
npm install kolosal-vision-mcp
```

## 🔑 Configuration

### Get Your API Key

1. Visit [Kolosal AI](https://kolosal.ai)
2. Sign up or log in to your account
3. Generate an API key from your dashboard

### Setup with Cursor IDE

Add this configuration to your Cursor MCP settings (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "kolosal-vision": {
      "command": "npx",
      "args": ["-y", "kolosal-vision-mcp"],
      "env": {
        "KOLOSAL_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Setup with Claude Desktop

Add this to your Claude Desktop config:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "kolosal-vision": {
      "command": "npx",
      "args": ["-y", "kolosal-vision-mcp"],
      "env": {
        "KOLOSAL_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Alternative: Using Global Installation

If you installed globally, replace the command configuration:

```json
{
  "mcpServers": {
    "kolosal-vision": {
      "command": "kolosal-vision-mcp",
      "env": {
        "KOLOSAL_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## 🛠️ Tool: `analyze_image`

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `image` | string | Yes | Image source: URL, local file path, or base64-encoded data |
| `description` | string | Yes | What to analyze (e.g., "Describe this image", "Extract text") |

### Supported Image Sources

1. **URLs** - `https://example.com/image.jpg`
2. **Local files** - `/path/to/image.png` or `./relative/path.jpg`
3. **Base64** - Raw base64-encoded image data

### Supported Formats

- JPEG / JPG
- PNG
- GIF
- WebP
- BMP

## 💡 Usage Examples

### In Cursor IDE

Simply reference an image file and ask questions:

```
Analyze @./photos/product.jpg and describe what you see
```

```
What text is visible in @./screenshots/document.png?
```

### Example Prompts

- "What objects are in this image?"
- "Describe the scene in detail"
- "Extract any visible text (OCR)"
- "What is the main subject?"
- "Describe the colors and composition"
- "Are there any people? What are they doing?"
- "What brand logos are visible?"
- "Is this image appropriate for a professional website?"

### Response Format

The tool returns structured responses:

```markdown
## Image Analysis

[Detailed analysis based on your query]

## Details
1. [Key observation 1]
2. [Key observation 2]
3. [Key observation 3]
...
```

## 🔧 Development

### Prerequisites

- Node.js 18+
- npm or yarn

### Setup

```bash
# Clone the repository
git clone https://github.com/madebyaris/kolosal-vision-mcp.git
cd kolosal-vision-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development mode (watch)
npm run dev
```

### Project Structure

```
kolosal-mcp-vision/
├── src/
│   └── index.ts      # Main MCP server implementation
├── dist/             # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
```

## 🐛 Troubleshooting

### "KOLOSAL_API_KEY environment variable is not set"

Make sure you've added your API key to the MCP configuration's `env` section.

### "Invalid image format"

Ensure your image is in a supported format (JPEG, PNG, GIF, WebP, or BMP). PDF files are not currently supported.

### "Failed to download image"

Check that the URL is accessible and returns a valid image. Some URLs may require authentication or have CORS restrictions.

### MCP Server Not Loading

1. Restart your IDE/client after configuration changes
2. Check the MCP configuration JSON syntax
3. Verify the API key is correct

## 📄 License

MIT © [Aris Setiawan](https://github.com/madebyaris)

## 🔗 Links

- [Kolosal AI](https://kolosal.ai) - Get your API key
- [MCP Documentation](https://modelcontextprotocol.io) - Learn more about MCP
- [GitHub Repository](https://github.com/madebyaris/kolosal-vision-mcp)
- [npm Package](https://www.npmjs.com/package/kolosal-vision-mcp)

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request