Skip to main content
Glama

Kolosal Vision MCP

npm version License: MIT

An MCP (Model Context Protocol) server that provides AI-powered image analysis and OCR using the Kolosal Vision API. 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

Related MCP server: MCP Image Recognition Server

šŸ“¦ Installation

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

npx kolosal-vision-mcp

Global Installation

npm install -g kolosal-vision-mcp

Local Installation

npm install kolosal-vision-mcp

šŸ”‘ Configuration

Get Your API Key

  1. Visit 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):

{
  "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

{
  "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:

{
  "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:

## 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

# 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

šŸ¤ 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

Available Tools

1 tool
analyze_imageA

Analyze an image using Kolosal Vision AI. Provide an image (URL or base64-encoded) and a description of what you want to know about it. The tool will return a detailed analysis based on your query.

Inputs: image (required), description (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of confusion or overlap. The tool's purpose is clear and distinct, so agents cannot misselect.

    Naming Consistency5/5

    The single tool name 'analyze_image' follows a clear verb_noun pattern. Consistency is trivially maintained since there are no other tools to compare.

    Tool Count3/5

    At only one tool, the server feels thin even though it serves a narrow purpose. It is on the borderline of the acceptable range, as a vision server might benefit from additional tools like model listing or batch analysis.

    Completeness5/5

    For the stated purpose of image analysis, the tool appears to cover the full lifecycle: it takes an image and query and returns analysis. There are no obvious gaps in the surface for this domain.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI-powered image analysis capabilities including captioning, visual question answering, object detection, and coordinate pointing for both local files and remote URLs through the Moondream vision language model.
      48
      MIT

    Appeared in Searches