ownta-mcp

OWNTA 的 MCP 服务端（stdio）：把出图、图像处理、技能与百科只读封装成 Agent 可直接调用的 8 个工具。 不需要克隆本仓库，装好包 + 一把 Key 就能用。

安装

pip install ownta-mcp
# 或者
uv tool install ownta-mcp

需要 Python >= 3.10。装完会得到命令 ownta-mcp（也可以 python -m mcp_server）。

1. 拿一把 Key

登录 https://ownta.ai → 设置 → API Key → 新建。

默认 scopes 是五个值：img.gen（出图）、vid.gen、llm.chat、img.ops（图像处理）、 lib.read。只让 Agent 出图就把 img.ops 去掉；Key 建完不能改 scopes，要改只能重建。 存量 Key 会在服务端启动迁移时自动补上 img.ops / lib.read，不需要重建。

Key 等同账户权限（能出图、能扣点），不要提交进仓库或贴进公开对话。

2. 配到客户端

通用形状（Claude Desktop / Cursor 都是 mcpServers 这一层）：

{
  "mcpServers": {
    "ownta": {
      "command": "ownta-mcp",
      "env": {
        "OWNTA_GW_API_KEY": "sk-ownta-...",
        "OWNTA_GW_BASE_URL": "https://ai.ownta.ai"
      }
    }
  }
}

• Claude Desktop：%APPDATA%\Claude\claude_desktop_config.json（Windows）/ ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
• Cursor：~/.cursor/mcp.json
• VS Code：.vscode/mcp.json（键名是 servers，其余字段相同）

Windows 上客户端找不到 ownta-mcp 时，把 command 写成 pip 的 Scripts 全路径， 例如 C:\Users\<you>\AppData\Local\Programs\Python\Python312\Scripts\ownta-mcp.exe。

OWNTA_GW_BASE_URL 可省略，默认就是 https://ai.ownta.ai。

3. 先跑这一句

用 ownta 的 generate_image 画一只在雨林里的蓝顶亚马逊鹦鹉，1024x1024，然后轮询到出图，把图片 URL 给我。

Agent 应该先拿到 job_id，再调 query_job 取 url。第一次调用会扣点； 余额不足会收到 insufficient_credits。

工具

apply_op 的 13 档按点数分四组（价目真值在网关 Price 表）：

• 0 点：compress / crop / watermark / print_text / whitebg
• 2 点：matting / kit　　4 点：seamless　　5 点：upscale　　6 点：seamless_pro
• 8 点：print_extract　　10 点：inpaint_swap　　16 点：outpaint

apply_op 的 src 只收本站 CDN 对象（image/ uploads/ processed/ 前缀）， 不收外链与 base64；generate_image 的参考图反过来只收 data URL / 裸 base64，不收 http URL。

错误码

回包 ok=false 时按 code 分支（原样透传网关的 detail.reason）：

已知边界

• 只有 stdio，没有远程 HTTP 端点：Agent 必须跑在能起子进程的客户端里。
• 一次任务不等待出图；generate_image 返回后必须用 query_job 轮询。
• stdout 是 JSON-RPC 通道，本包日志只写 stderr；不要用 print 调试。

从源码安装（开发）

cd gateway/mcp_server
pip install -e .

版本：0.1.0