three.ws vision MCP server
Commit Nov 10, 2026Enables AI agents to analyze, describe, and perform OCR on images using the three.ws vision pipeline.
Also known as nirholas/image-analysis-mcp
- Stars
- 10
- Tools
- 3
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- —
What is three.ws vision MCP?
three.ws vision enables AI agents to analyze, describe, and perform OCR on images using the three.ws vision pipeline. It exposes 3 tools, such as analyze_image, describe_image, get_vision_status.
Summary generated from the project's README
About three.ws vision MCP server
Giving AI assistants the ability to see and interpret visual data is what this server enables through the three.ws vision pipeline. Developers can integrate image understanding into Claude Desktop, Cursor, or Claude Code by providing either a public HTTPS URL or a base64 encoded image. The system supports JPEG, PNG, WebP, and GIF formats up to 12 MB.
Users can perform visual Q&A, optical character recognition, and scene classification using the analyze_image tool. For generating captions or alt-text, the describe_image tool offers adjustable detail levels and specific focus areas. The get_vision_status tool allows clients to check supported formats and provider availability.
This setup requires Node.js 20 or higher and functions without an API key, as it prioritizes free NVIDIA NIM vision models. While no key is required for basic use, providing a THREE_WS_API_KEY can increase rate limits from the standard IP-based tier to a per-user tier.
What you can do with it
- 1Generate descriptive alt-textCreate natural language descriptions for images with varying levels of detail.
- 2Perform visual question answeringAsk specific questions about the contents of a scene or a render.
- 3Verify vision capabilitiesCheck which image formats are currently accepted by the vision provider.
Written from the project's README. Every use case is checked against a quote from it.
three.ws vision MCP tools 3
Detected from the READMEanalyze_imagedescribe_imageget_vision_status
| analyze_image | — | |
| describe_image | — | |
| get_vision_status | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenirholas/image-analysis-mcp is public and reachablegithub.com/nirholas/image-analysis-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-10github.com/nirholas/image-analysis-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model3 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubA Model Context Protocol server that gives any AI assistant image understanding over stdio. Pass an image as a public URL or base64 and the agent can read the text in a screenshot, identify what's in a scene, critique a 3D/avatar render, or write alt-text — all live, read-only, no key required.
Every answer comes from the three.ws vision pipeline: free NVIDIA NIM vision models lead every request, with an automatic server-side paid backstop behind them. The caller never pays and needs no provider key — point THREE_WS_BASE at a deployment and go.
Install
npm install @three-ws/vision-mcp
Or run with npx (no install):
npx @three-ws/vision-mcp
Quick start
Claude Code, one line:
claude mcp add vision -- npx -y @three-ws/vision-mcp
Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):
{
"mcpServers": {
"vision": {
"command": "npx",
"args": ["-y", "@three-ws/vision-mcp"]
}
}
}
Inspect the surface with the MCP Inspector:
npx -y @modelcontextprotocol/inspector npx @three-ws/vision-mcp
Tools
| Tool | Type | What it does |
|---|---|---|
analyze_image |
read-only | Answer a prompt about an image — visual Q&A, OCR (read a screenshot), classification, or critiquing a render. |
describe_image |
read-only | Natural-language description for alt text or a caption, steerable by detail level and focus. |
get_vision_status |
read-only | Report whether a vision provider is live and which image formats are accepted. No image, no cost. |
All three tools are read-only — they look at an image, they never store or mutate anything. A VLM is non-deterministic and the live provider chain moves, so none are idempotent.
Input parameters
analyze_image — prompt (required), and exactly one of imageUrl (public https) or image (base64 / data URI). Optional imageType (for raw base64), maxTokens (16–2048, default 512).
describe_image — exactly one of imageUrl or image. Optional imageType, detail (brief | standard | detailed, default standard), focus (an aspect to emphasize).
get_vision_status — no parameters.
Example
// analyze_image — read the text in a screenshot
> { "imageUrl": "https://three.ws/render.png", "prompt": "What does the banner text say?" }
{
"ok": true,
"text": "The banner reads \"three.ws — 3D AI agents\".",
"provider": "nvidia",
"model": "nvidia/nemotron-nano-12b-v2-vl",
"prompt": "What does the banner text say?",
"image_source": "url"
}
// describe_image — alt text from a base64 image
> { "image": "data:image/png;base64,iVBORw0KG...", "detail": "brief" }
{
"ok": true,
"description": "A seagull in profile against a blurred coastal background.",
"detail": "brief",
"provider": "nvidia",
"model": "nvidia/nemotron-nano-12b-v2-vl",
"image_source": "base64"
}
// get_vision_status — gate a "describe this" affordance
> {}
{
"ok": true,
"configured": true,
"image_types": ["image/jpeg", "image/png", "image/webp", "image/gif"],
"max_image_mb": 12
}
Images may be JPEG, PNG, WebP, or GIF, up to 12 MB. Base64 inputs are size-checked locally before upload; imageUrl must be a public https URL (the vision server fetches it, so private/loopback hosts are rejected).
Pricing & auth
There is no charge to the caller and no key is needed. The platform runs every request against free NVIDIA NIM vision lanes first and falls back to a paid model only on its own infrastructure — that cost is the platform's, transparent to you.
The endpoint is rate-limited per IP. To raise your limit to the per-user tier, set the optional THREE_WS_API_KEY (a three.ws API key); it is sent as a bearer token. It is never required to use the free model.
Requirements
- Node.js >= 20.
- Network access to
https://three.ws(or your ownTHREE_WS_BASE).
Environment variables
| Variable | Required | Default | Purpose |
|---|---|---|---|
THREE_WS_BASE |
no | https://three.ws |
Which deployment to call. |
THREE_WS_TIMEOUT_MS |
no | 30000 |
Per-request timeout (a call may chain across free lanes). |
THREE_WS_API_KEY |
no | — | Optional bearer token to raise the rate limit to per-user. |
Links
- Homepage: https://three.ws
- Changelog: https://three.ws/changelog
- Issues: https://github.com/nirholas/three.ws/issues
- License: Apache-2.0 — see LICENSE
License
All rights reserved. See LICENSE.
Star History
Support the project
If image-analysis-mcp saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.
Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit
Built for AI agents too
Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/image-analysis-mcp and it has the context it needs.
More from the same author
- All repositories by nirholas: the full catalog, grouped by topic
- three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
- Questions or ideas: open an issue or start a discussion
Contributors
three.ws vision MCP questions
What tools does three.ws vision MCP provide?
It exposes 3 tools, including analyze_image, describe_image, get_vision_status.
Do I need an API key to use this?
No, the server works without a key using free NVIDIA NIM vision lanes. You can optionally provide a THREE_WS_API_KEY to increase rate limits.
What image formats are supported?
The server accepts JPEG, PNG, WebP, and GIF formats up to 12 MB.
Can I use private images via URL?
No, imageUrl must be a public https URL because the vision server must be able to fetch it.