# image-mcp

基于 DashScope 视觉模型的本地 MCP server，用于识别本地或远程图片，并默认以 XML 形式返回图片内容，帮助 AI 理解图片。

## 安装

```sh
npm install
```

## MCP 配置

模型配置通过 MCP client 的 `env` 注入到 server 进程，不需要也不应该作为 tool 参数传递。

```json
{
  "mcpServers": {
    "image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/image-mcp/src/index.mjs"],
      "env": {
        "DASHSCOPE_API_KEY": "your-api-key",
        "VISION_MODEL": "qwen-vl-plus",
        "DASHSCOPE_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1"
      }
    }
  }
}
```

`DASHSCOPE_BASE_URL` 可省略，默认使用 `https://dashscope.aliyuncs.com/compatible-mode/v1`。

## Tool

`recognize_image`

- `image_path`: 本地图片路径，和 `image_url` 二选一。
- `image_url`: 远程图片 URL，和 `image_path` 二选一。
- `prompt`: 可选识图提示词，默认值为 `识别图像内容，使用xml形式输出，帮助ai理解图片内容`。
- `max_tokens`: 可选最大输出 token 数，默认 `1024`。

## CLI

```sh
npm run vision -- ./dist/ScreenShot_2026-08-01_155219_072.png "识别图像内容，使用xml形式输出，帮助ai理解图片内容"
npm run vision -- --url https://example.com/image.png
```

## 本地 npm 使用

如果只是本机使用，不需要发布到 npm registry。推荐用 `npm link` 或 `npm pack`。

### 方式一：npm link

在项目目录执行：

```sh
npm install
npm link
```

然后 MCP 配置可以直接使用全局命令：

```json
{
  "mcpServers": {
    "image-mcp": {
      "command": "image-mcp",
      "args": [],
      "env": {
        "DASHSCOPE_API_KEY": "your-api-key",
        "VISION_MODEL": "qwen-vl-plus",
        "DASHSCOPE_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1"
      }
    }
  }
}
```

如果之后修改了源码，一般不需要重新 link；重启 MCP client 即可加载新代码。

取消本地链接：

```sh
npm unlink -g image-mcp
```

### 方式二：npm pack

如果想模拟正式 npm 包安装，但仍然只在本地使用：

```sh
npm install
npm pack
npm install -g ./image-mcp-1.0.0.tgz
```

安装后同样可以在 MCP 配置中使用：

```json
{
  "mcpServers": {
    "image-mcp": {
      "command": "image-mcp",
      "args": [],
      "env": {
        "DASHSCOPE_API_KEY": "your-api-key",
        "VISION_MODEL": "qwen-vl-plus"
      }
    }
  }
}
```

升级本地包时重新执行：

```sh
npm pack
npm install -g ./image-mcp-1.0.0.tgz
```

### 检查命令

确认全局命令可用：

```sh
which image-mcp
image-mcp
```

`image-mcp` 是 MCP stdio server，直接运行后会等待 MCP client 输入；没有输出不代表失败。实际验证建议在 MCP client 中查看是否能列出 `recognize_image` 工具。


## 特殊说明

项目扩展自 : https://github.com/asuojun/claude-vision-skill/tree/master