内容
# openart-mcp
MCP 服务器 + Claude 技能，用于 OpenArt.ai。OpenArt 没有公开 API，因此该项目通过 Playwright 模拟登录用户操作其网页 UI。
## 内容
- **MCP 服务器** (`src/`) — 暴露 5 种工具，自动化 OpenArt 角色 + 视频工作流程
- **Claude 技能** (`skills/openart/SKILL.md`) — 告诉 Claude 何时以及如何调用 MCP 工具
## 工具
| 工具 | 用途 |
|---|---|
| `openart_list_characters` | 列出 OpenArt 账户中的所有角色 |
| `openart_get_character` | 获取角色 ID 的详细信息 |
| `openart_create_character` | 从本地图像创建新角色 |
| `openart_generate_video` | 生成角色朗读脚本的视频 |
| `openart_get_video_status` | 检查生成的视频渲染状态 + URL |
## 安装
### 1. 安装 MCP 服务器
```bash
git clone https://github.com/jbertus/openart-mcp.git
cd openart-mcp
npm install
npx playwright install chromium
npm run build
npm run login # 打开浏览器，登录 OpenArt，完成登录后按 Enter
```
登录步骤将 Playwright `storageState` JSON 保存到 `~/.openart-mcp/auth.json`（或 Windows 上的 `%USERPROFILE%\.openart-mcp\auth.json`）。服务器在后续每次工具调用时重复使用该会话。
### 2. 将 MCP 注册到客户端
**Claude 代码 / Claude 桌面版** — 添加到 MCP 配置（`~/.claude/mcp.json` 或等效文件）：
```json
{
"mcpServers": {
"openart": {
"command": "node",
"args": ["<克隆仓库的绝对路径>/dist/index.js"]
}
}
}
```
**其他 MCP 客户端** — 指向 `node <仓库>/dist/index.js`，使用 stdio 传输。
### 3. 安装配套技能（可选但推荐）
```bash
npx skills add https://github.com/jbertus/openart-mcp --skill openart
```
该技能教导 Claude 何时调用哪个工具以及如何格式化参数。没有它，Claude 仍然可以使用 MCP，但您需要更明确地表达意图。
## 配置
环境变量（均可选）：
| 变量 | 默认值 | 用途 |
|---|---|---|
| `OPENART_STORAGE_STATE` | `~/.openart-mcp/auth.json` | Playwright 会话 JSON 的路径 |
| `OPENART_HEADLESS` | `true` | 设置为 `false` 以在自动化过程中显示浏览器 |
## 选择器设置（一次性）
`src/tools.ts` 中的工具附带占位符 DOM 选择器，标记为 `TODO`。OpenArt 的 UI 可能会随时间变化，因此需要针对实时网站捕获选择器：
```bash
npx playwright codegen https://openart.ai/suite/characters-and-worlds
```
点击每个工具流程的 UI。Playwright 生成真实的选择器。将它们粘贴到 `src/tools.ts` 中的 TODO 位置，重新构建（`npm run build`），然后工具即可使用。
如果选择器稍后损坏（OpenArt 重新设计），请重复此步骤。
## 风险
- **对 UI 更改脆弱。** 每次 OpenArt 重新设计都可能破坏选择器。需要重新运行 codegen 并重新修补。
- **比真正的 API 更慢。** 每个工具调用都会启动浏览器会话并等待页面加载。
- **会话可能过期。** 当提示时，重新运行 `npm run login`。
- **OpenArt 可能会阻止自动化。** 反机器人检测可能会限制速率或封禁您的帐户。请谨慎使用。如果被封禁，没有追索权。
## 测试
```bash
npm run inspect # 启动 MCP Inspector 以对抗服务器
```
## 贡献
欢迎 PR。如果 OpenArt 的 UI 更改，选择器损坏，请打开一个问题，附上新的选择器和需要更新的工具流程的简要描述。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
