Kolosal Vision MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Kolosal Vision MCP what's in this photo @./vacation/hawaii.jpg?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Kolosal Vision MCP
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-mcpGlobal Installation
npm install -g kolosal-vision-mcpLocal Installation
npm install kolosal-vision-mcpš Configuration
Get Your API Key
Visit Kolosal AI
Sign up or log in to your account
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 |
| string | Yes | Image source: URL, local file path, or base64-encoded data |
| string | Yes | What to analyze (e.g., "Describe this image", "Extract text") |
Supported Image Sources
URLs -
https://example.com/image.jpgLocal files -
/path/to/image.pngor./relative/path.jpgBase64 - 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 seeWhat 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 devProject 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
Restart your IDE/client after configuration changes
Check the MCP configuration JSON syntax
Verify the API key is correct
š License
MIT Ā© Aris Setiawan
š Links
Kolosal AI - Get your API key
MCP Documentation - Learn more about MCP
š¤ Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add some amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
Available Tools
1 toolanalyze_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
Scored across 1 tool
With only one tool, there is no possibility of confusion or overlap. The tool's purpose is clear and distinct, so agents cannot misselect.
The single tool name 'analyze_image' follows a clear verb_noun pattern. Consistency is trivially maintained since there are no other tools to compare.
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.
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
Run AI-powered analysis on images including moderation, captioning, tagging, and more.
Search photos and video moments by visual meaning, people, dates, and folders across local libraries, Apple Photos, and OneDrive. Manage collections, groups, favorites, people, and duplicate review. Synced metadata remains searchable while the desktop is offline; local and Apple Photos media access needs the owning device online with remote access enabled. OneDrive media can be accessed directly from the cloud. OAuth or Bearer API keys. Paid Cloud Access required; hosted visual search uses prepaid credits. Text-in-image search is semantic matching, not guaranteed exact OCR. Setup: https://organizewith.ai/en/guides/connect-ai-assistants
Analyze images and videos with Gemini to get fast, reliable visual insights. Handle content from Uā¦
Image & PDF tools for AI agents: compress, convert, resize, PDF, AI vision, pipeline.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables image analysis and understanding using Vision Language Models through OpenAI-compatible APIs. Supports analyzing images from URLs or local files with custom prompts.12MIT
- FlicenseNot gradedqualityFmaintenanceEnables image analysis and recognition through multiple LLM vision models (Gemini, GPT-4o, Qwen-VL, Doubao) by accepting image URLs or Base64 data and returning text descriptions or answers to questions about the images.1-
- AlicenseNot gradedqualityDmaintenanceProvides 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.48MIT
- AlicenseBqualityDmaintenanceEnables vision capabilities for any AI model by routing image analysis requests through OpenRouter's vision models. It provides tools to analyze images from URLs, local file paths, or base64 data.2630 npm19MIT