Metadata-Version: 2.4
Name: mcp-image-server
Version: 0.1.0
Summary: Local image bed MCP Server — exposes local images via HTTP for inline display in AI clients
Project-URL: Homepage, https://gitee.com/xiaoye12345/image-server
Project-URL: Repository, https://gitee.com/xiaoye12345/image-server
Author: sheny
License-Expression: MIT
License-File: LICENSE
Keywords: image-server,local-image-bed,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# MCP Image Server

本地图床 MCP Server，通过 HTTP 服务将本地图片暴露为可访问的 URL，用于在 Cherry Studio 等支持 Markdown 渲染的 AI 客户端中内联显示图片。

## 工作原理

1. 以 MCP Server 形式运行，由 Cherry Studio 自动管理进程生命周期
2. 启动后在本地开启 HTTP 图片服务（默认端口 18090）
3. AI 通过系统提示词知道 URL 格式，直接输出 Markdown 图片链接
4. 客户端渲染 Markdown 时自动从本地 HTTP 服务加载图片

```
AI 输出: ![照片](http://localhost:18090/image?path=E%3A%5Cphotos%5Ctest.png&t=1713936000)
         ↓
Cherry Studio 渲染 Markdown
         ↓
浏览器请求 localhost:18090 → HTTP 服务读取本地文件 → 返回图片
```

## 安装

推荐使用 `uv tool install`，无需克隆仓库，任意电脑一行命令搞定：

```bash
uv tool install git+https://gitee.com/xiaoye12345/image-server.git
```

或用 pip（需要先激活你想要的虚拟环境）：

```bash
pip install git+https://gitee.com/xiaoye12345/image-server.git
```

安装完成后会自动注册 `mcp-image-server` 命令，MCP 配置中直接引用命令名即可，**无需填写任何路径**。

## 配置

### Cherry Studio MCP 服务器

通过 JSON 导入：

```json
{
  "mcpServers": {
    "image-server": {
      "type": "stdio",
      "command": "mcp-image-server"
    }
  }
}
```

### 系统提示词

在 Cherry Studio 的系统提示词中添加：

```
当需要显示本地图片时，直接用 Markdown 图片格式输出：
![描述](http://localhost:18090/image?path=<URL编码的文件绝对路径>&t=<文件修改时间戳>)
路径中的中文、空格等特殊字符必须 URL 编码。
`t` 参数为文件修改时间戳，用于避免缓存导致图片更新后显示旧版本。
示例：![风景](http://localhost:18090/image?path=E%3A%5Cphotos%5Ctest.png&t=1713936000)
```

## 升级

```bash
uv tool install --upgrade git+https://gitee.com/xiaoye12345/image-server.git
```

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `IMAGE_SERVER_PORT` | `18090` | HTTP 服务监听端口 |

## URL 格式

```
http://localhost:18090/image?path=<URL编码的文件路径>&t=<文件修改时间戳>
```

- `path`：URL 编码的本地图片绝对路径
- `t`：伪参数，值为文件修改时间戳（秒），用于打破缓存。图片更新后时间戳改变，URL 不同，浏览器不会使用缓存。服务端忽略此参数。

支持的图片格式：`.png` `.jpg` `.jpeg` `.gif` `.svg` `.webp` `.bmp`

## License

MIT
