three.ws Vision

@three-ws/vision-mcp

让任何 AI Agent 都能看见 — 通过 three.ws 视觉管线分析和描述图像，优先免费且无需密钥。

---

一个 Model Context Protocol 服务，通过 stdio 为任何 AI 助手提供图像理解能力。传入公开 URL 或 base64 格式的图像，Agent 就能读取屏幕截图中的文字、识别场景内容、点评 3D／头像渲染图，或撰写替代文本 — 全程实时、只读且无需密钥。

每个回答都来自 three.ws 视觉管线：每个请求都优先使用免费的 NVIDIA NIM 视觉模型，并在其后自动接入服务端付费备用方案。调用方无需付费，也不需要提供商密钥 — 将 THREE_WS_BASE 指向一个部署实例即可开始使用。

安装

npm install @three-ws/vision-mcp

也可以使用 npx 运行（无需安装）：

npx @three-ws/vision-mcp

快速开始

Claude Code，一行命令：

claude mcp add vision -- npx -y @three-ws/vision-mcp

Claude Desktop / Cursor（claude_desktop_config.json 或 mcp.json）：

{
	"mcpServers": {
		"vision": {
			"command": "npx",
			"args": ["-y", "@three-ws/vision-mcp"]
		}
	}
}

使用 MCP Inspector 检查可用功能：

npx -y @modelcontextprotocol/inspector npx @three-ws/vision-mcp

工具

工具	类型	功能
analyze_image	只读	回答有关图像的提示词 — 视觉问答、OCR（读取屏幕截图）、分类或点评渲染图。
describe_image	只读	生成自然语言描述，用作替代文本或说明文字；可通过细节级别和关注重点进行调整。
get_vision_status	只读	报告视觉提供商是否在线，以及支持哪些图像格式。无需图像，不产生费用。

这三个工具均为只读 — 它们只查看图像，不会存储或修改任何内容。VLM 具有非确定性，在线提供商链也会变化，因此这些工具都不具备幂等性。

输入参数

analyze_image — prompt（必填），以及 imageUrl（公开 https）或 image（base64／data URI），二选一且必须且只能提供其中一个。可选参数：imageType（用于原始 base64）、maxTokens（16–2048，默认值为 512）。

describe_image — imageUrl 或 image，二选一且必须且只能提供其中一个。可选参数：imageType、detail（brief | standard | detailed，默认值为 standard）、focus（要强调的方面）。

get_vision_status — 无参数。

示例

// analyze_image: read the text in a logo image
> { "imageUrl": "https://three.ws/logo.png", "prompt": "What does this logo say?" }
{
  "ok": true,
  "text": "The logo reads \"three.ws\".",
  "provider": "nvidia",
  "model": "nvidia/nemotron-nano-12b-v2-vl",
  "prompt": "What does this logo 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
}

示例

可直接运行且无需密钥的示例位于 examples/：

node examples/list-tools.mjs     # every tool with its full input schema
node examples/read-an-image.mjs  # status + alt text + OCR on a live image

两个示例都会通过 stdio 启动此服务，并调用真实的视觉管线。所有工具 均为只读，因此不会存储任何内容，也不会产生费用。预期输出请参阅 examples/README.md。

图像格式可以是 JPEG、PNG、WebP 或 GIF，大小最多为 12 MB。上传前会在本地检查 base64 输入的大小；imageUrl 必须是公开的 https URL（视觉服务会获取该 URL，因此会拒绝私有或环回主机）。

定价与身份验证

调用方无需付费，也无需密钥。平台会先将每个请求路由到免费的 NVIDIA NIM 视觉通道，只有在自有基础设施上才会回退到付费模型——这笔费用由平台承担，对你透明。

该端点按 IP 限流。若要将限额提高到每用户档位，请设置可选的 THREE_WS_API_KEY（three.ws API 密钥）；它会作为 bearer token 发送。使用免费模型绝不需要该密钥。

要求

• Node.js >= 20。
• 可访问网络 https://three.ws（或你自己的 THREE_WS_BASE）。

环境变量

变量	必需	默认值	用途
THREE_WS_BASE	否	https://three.ws	要调用的部署。
THREE_WS_TIMEOUT_MS	否	30000	单次请求超时（一次调用可能串联多个免费通道）。
THREE_WS_API_KEY	否	—	可选 bearer token，可将限流提高到每用户档位。

链接

• 主页：https://three.ws
• 更新日志：https://three.ws/changelog
• 问题反馈：https://github.com/nirholas/three.ws/issues
• 许可证：Apache-2.0，参见 LICENSE

---

_{属于 three.ws SDK 套件的一部分——3D AI Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}