Skip to main content
Glama
madebyaris

Kolosal Vision MCP

by madebyaris
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

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

Using npx (Recommended)

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

🔗 Links

🤝 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
imageYesThe image to analyze. Can be a URL (http:// or https://) that will be downloaded, a local file path, or base64-encoded image data. When the user references an image with @ (e.g., @path/to/image.png), use the resolved file path directly.
descriptionYesWhat you want to analyze or check in the image. Examples: 'What objects are in this image?', 'Describe the scene in detail', 'Extract any visible text', 'What is the main subject?'

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It mentions the output ("will return a detailed analysis") but does not disclose side effects, limitations, or processing details beyond what the schema already provides. This is acceptable but minimal for a read-only analysis tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loading the purpose. The final sentence "The tool will return a detailed analysis based on your query" is somewhat redundant with the first and second sentences, but the overall structure is compact and easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool with no output schema, the description adequately explains what the tool does and how to invoke it. It lacks details about return format, error handling, or size limits, but these are not critical for basic usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description repeats that the image can be a URL or base64, but does not add meaningful semantics beyond the schema's existing descriptions of 'image' and 'description'. No extra value over the structured data.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: "Analyze an image using Kolosal Vision AI." It specifies a concrete verb ('analyze') and resource ('image'). Since there are no sibling tools to differentiate against, it cannot fully reach a 5 but is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage instructions: "Provide an image (URL or base64-encoded) and a description of what you want to know about it." It implicitly tells when to use the tool (when image analysis is needed) but does not mention alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 1 tool updatev1.0.0
    • First observedanalyze_image
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Moondream MCP Server

    ColeMurray
    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