Sirv AI Studio

Sirv AI MCP 服务

Sirv AI Studio 的 MCP（Model Context Protocol）服务——用于 AI 图像和视频处理。

功能

此 MCP 服务提供 54 个工具，涵盖 AI 处理、资源管理、产品管理、Shopify 集成、供应商门户操作以及 Sirv CDN 文件管理：

图像处理

• sirv_remove_background - 使用 BiRefNet 或 Bria 去除图像背景
• sirv_upscale - 使用 ESRGAN、Clarity 或 Topaz 将图像放大 2-4 倍
• sirv_background_replace - 使用 AI 生成的场景替换图像背景
• sirv_object_removal - 去除图像中的物体，或根据提示词填充遮罩区域
• sirv_depth_map - 根据图像生成深度图

图像生成

• sirv_generate - 根据文本提示词生成图像
• sirv_image_to_image - 根据文本提示词转换图像
• sirv_image_translation - 翻译图像中的文本

产品 AI

• sirv_product_lifestyle - 创建产品生活方式照片
• sirv_virtual_try_on - 虚拟试穿服装

3D 与视频

• sirv_image_to_3d - 将图像转换为 3D 模型
• sirv_optimize_glb - 使用网格和纹理压缩优化 GLB 模型
• sirv_video_generation - 根据文本或图像生成视频
• sirv_video_upscale - 使用 SeedVR 或 Topaz 将视频放大 2 倍或 4 倍，使其达到商品列表所需的质量

批量操作

• sirv_batch_remove_background - 批量处理符合资格的图像
• sirv_batch_upscale - 批量放大符合资格的图像

工作流

• sirv_list_workflows - 列出已保存的工作流
• sirv_get_workflow - 获取工作流详情

资源管理（DAM）

• sirv_list_assets - 使用筛选和分页列出资源
• sirv_get_asset - 根据 ID 获取单个资源
• sirv_search_assets - 按文本搜索工作区资源，匹配每个单词或其词干
• sirv_find_similar_assets - 使用工作区视觉相似度索引查找视觉上相似的资源
• sirv_update_asset - 更新资源字段（文件名、替代文本、收藏状态）
• sirv_delete_asset - 软删除资源
• sirv_get_asset_metadata - 获取资源的自定义元数据
• sirv_update_asset_metadata - 更新自定义元数据字段
• sirv_generate_asset_alt_text - 使用 AI 为资源生成替代文本
• sirv_bulk_asset_operation - 批量收藏/取消收藏/删除/添加标签/移动
• sirv_import_asset_url - 从外部 URL 导入资源

产品管理（PIM）

• sirv_list_products - 使用筛选和分页列出产品
• sirv_get_product - 根据 ID 获取单个产品
• sirv_create_product - 创建新产品
• sirv_update_product - 更新产品字段
• sirv_delete_product - 删除产品
• sirv_search_products - 按名称或 SKU 快速搜索
• sirv_list_products_with_assets - 列出产品及其关联资源详情
• sirv_link_assets_to_product - 将资源关联到产品
• sirv_bulk_product_action - 批量删除、更新状态、关联资源

Shopify 集成

• sirv_shopify_status - 检查 Shopify 连接状态
• sirv_push_image_to_shopify - 通过经批准的发布计划，将 Studio 资源发布到 Shopify 产品
• sirv_sync_shopify_products - 在后台开始将 Shopify 产品和图像导入 PIM

供应商门户

• sirv_get_supplier_sftp_status - 检查符合资格的供应商门户 SFTP 连接详情
• sirv_get_supplier_review_assist_requirements - 检查供应商门户提交要求
• sirv_run_supplier_autofix - 对供应商图像运行会消耗额度的自动修复

Sirv CDN 文件管理

这些工具操作的是工作区已连接的 Sirv 账户，而不是 Studio 资源库：

• sirv_cdn_search_files - 分页并排序搜索 Sirv 文件
• sirv_cdn_get_file_metadata - 查看文件元数据
• sirv_cdn_manage_folder - 创建文件夹或列出文件夹内容
• sirv_cdn_upload_from_url - 从公开 URL 上传文件
• sirv_cdn_update_file_metadata - 设置标题、描述、标签或产品元数据
• sirv_cdn_update_file_tags - 添加或移除文件标签
• sirv_cdn_manage_file - 重命名、复制或删除文件

实用工具

• sirv_alt_text - 生成替代文本描述
• sirv_get_usage - 查看额度使用统计

组织上下文

• sirv_list_organizations - 列出已通过身份验证的用户可用的组织

所有 DAM、产品、Shopify、Supplier Portal 和 Sirv CDN 工具都接受可选的 orgId 参数，用于将请求限定到特定组织。如果省略，则使用用户的默认组织。服务会将 orgId 作为 X-Org-Id 标头发送，API 会根据用户的组织成员身份进行验证。

权限检查

每个 Studio 方案都包含 API 和 MCP 访问权限；管理员可以为工作区关闭此权限。随后，列表、获取、搜索、读取元数据、使用情况、组织和工作流读取等可预览读取的工具无需其他工具专属检查即可执行。修改工具、会消耗额度的直接 AI 工具、批量操作、视觉相似度、Shopify 交付/同步以及 Supplier Portal Pro 工具会在执行前调用 Studio 的 /api/mcp/authorize-tool 端点；如果工作区缺少相应权限，则会拒绝执行。

提示词

• prepare-listing-image（assetId）- 移除一张资源库图片的背景，在图片较小时进行放大，并撰写替代文本
• alt-text-sweep（folderId）- 查找文件夹中没有替代文本的图片，并在用户确认费用后撰写替代文本

安装

使用托管服务 https://mcp.sirv.studio，或运行 npm 包：

npx -y sirv-ai-mcp-server

请使用 1.0.5 或更高版本。更早的版本是旧版服务，发布于 2026-10-30 的 www.sirv.studio 切换之前。

从源代码构建：

bun install
bun run build
node dist/index.js

配置

环境变量

# Optional: Sirv AI Studio URL (default: https://www.sirv.studio)
SIRV_AI_BASE_URL="https://www.sirv.studio"

# Optional: API key for authentication (if not using OAuth)
SIRV_AI_API_KEY="your-api-key"

# Transport mode: "stdio" (default) or "http"
MCP_TRANSPORT="stdio"

# HTTP server settings (when using http transport)
MCP_HTTP_PORT=3001
MCP_HTTP_HOST=0.0.0.0
MCP_BASE_URL="https://your-mcp-server.com"

# HTTPS (optional - can also use reverse proxy)
MCP_SSL_KEY_PATH="/path/to/key.pem"
MCP_SSL_CERT_PATH="/path/to/cert.pem"

# Security: IP allowlisting
MCP_ENABLE_IP_ALLOWLIST="true"
MCP_ALLOWED_IPS="1.2.3.4,5.6.7.8/24"

# CORS: Allowed origins (comma-separated)
MCP_CORS_ORIGINS="https://claude.ai,https://your-app.com"

传输模式

Stdio 传输（默认）

用于与 Claude Desktop 和 Claude Code 进行本地集成。

bun run start
# or
bun run dev

HTTP 传输

用于可通过 HTTPS 访问的远程/托管部署。

bun run start:http
# or
bun run dev:http

在 HTTP 模式下运行时，服务会公开以下端点：

• / - MCP 协议端点（也接受 /mcp，以保持兼容性）
• /health - 健康检查端点
• /.well-known/oauth-authorization-server - OAuth 2.0 元数据
• /.well-known/oauth-protected-resource - 受保护资源元数据

安全功能

请求限制

HTTP 请求接受不超过 1 MiB 的未压缩 JSON。工具参数的数组元素和对象成员总数（包括嵌套值）不得超过 10,000。较大的请求请拆分成多个较小的调用。文件上传使用 URL，而非内联字节。

每位已登录的调用者每分钟最多可发送 100 个请求。每个 IP 地址每分钟最多可发送 30 个无效 API 密钥。过期的 OAuth 令牌不计入此限制。

OAuth 2.0 支持

服务通过 PKCE 实现 OAuth 2.0，以确保身份验证安全：

• 使用 S256 代码质询的授权码流程
• 支持令牌刷新
• 在 ~/.sirv-ai/tokens.json 中安全存储令牌

工具安全注释

所有工具都包含适当的 MCP 安全注释：

• readOnlyHint - 指示工具是否只读取数据
• destructiveHint - 指示工具是否可能删除或覆盖数据
• idempotentHint - 指示重复调用是否会产生相同结果
• openWorldHint - 指示工具是否会访问外部服务

CORS 配置

在 HTTP 模式下运行时，CORS 配置用于基于浏览器的身份验证：

• 默认允许的来源：https://claude.ai、https://console.anthropic.com
• 可通过 MCP_CORS_ORIGINS 环境变量自定义
• 正确处理预检请求并支持凭据

IP 允许列表

可选的基于 IP 的访问控制：

• 预先配置 Claude.ai/Claude Code 的 IP 范围
• 使用 MCP_ENABLE_IP_ALLOWLIST=true 启用
• 通过 MCP_ALLOWED_IPS 添加自定义 IP/CIDR 范围

HTTPS 支持

用于生产部署：

1. 直接使用 HTTPS：设置 MCP_SSL_KEY_PATH 和 MCP_SSL_CERT_PATH
2. 反向代理：在 nginx/Caddy 后方运行 HTTP，并由其终止 TLS

在 Claude Desktop 中使用

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "sirv-ai": {
      "command": "npx",
      "args": ["-y", "sirv-ai-mcp-server"],
      "env": {
        "SIRV_AI_BASE_URL": "https://www.sirv.studio"
      }
    }
  }
}

在 Claude Code 中使用

将以下内容添加到 Claude Code MCP 设置中：

{
  "mcpServers": {
    "sirv-ai": {
      "command": "npx",
      "args": ["-y", "sirv-ai-mcp-server"],
      "env": {
        "SIRV_AI_BASE_URL": "https://www.sirv.studio"
      }
    }
  }
}

在 ChatGPT 中使用

对于托管服务，请使用 https://mcp.sirv.studio 作为 MCP 连接器 URL。通过 https://mcp-dev.sirv.studio 添加的连接器 仍可正常工作。Studio 会在 https://www.sirv.studio 处理登录和授权。 所有 Studio 方案都可以连接。当工作区的积分用完时，工具会返回指向 Studio「购买积分」页面的链接。 此连接方式与使用 OpenAPI 规范的 ChatGPT Actions 相互独立。

请使用 ChatGPT 连接器提供的回调 URL。Studio 接受 https://chatgpt.com/connector/oauth/<id>，其中包含一个由 字母、数字、下划线或连字符组成的 ID 段；也接受旧版回调 https://chatgpt.com/connector_platform_oauth_redirect。此 URL 还必须与客户端注册的重定向 URI 相匹配。OAuth 仍要求使用 PKCE S256。请参阅 MCP 开发者文档。

在当前源码中，十个图像结果工具会附带交互式图像 组件。账户、资源、产品、批量、工作流、视频和 3D 工具会返回 不带该组件的工具结果。对于多图像生成，组件会预览第一个结果，而非图库。

该组件使用 MIME 类型为 text/html;profile=mcp-app 的 MCP Apps 资源 ui://widget/sirv-studio-v3.html。 这是对服务器实现的说明，并不表示该应用已列入 ChatGPT 目录。

远程服务部署

如需远程托管 MCP 服务（可通过 claude.ai 访问）：

请区分以下两个来源：

• SIRV_AI_BASE_URL 是提供 OAuth 和 API 请求的 Studio 应用。
• MCP_BASE_URL 是客户端用于访问 MCP 服务的公共来源。 它提供对外公布的 OAuth 资源和组件域名。

Docker Compose 配置默认分别使用 https://www.sirv.studio 和 https://mcp.sirv.studio。 若部署到其他位置，请明确设置这两个值。

连接客户端前，请检查发现信息：

curl --fail https://mcp.sirv.studio/.well-known/oauth-protected-resource
curl --fail https://mcp.sirv.studio/.well-known/oauth-authorization-server

对于这些默认值，resource 应为 https://mcp.sirv.studio， issuer 和唯一的 authorization_servers 条目应为 https://www.sirv.studio。授权、令牌和注册 端点应使用 Studio 来源。

1. 使用 HTTPS 部署

# Using SSL certificates directly
MCP_TRANSPORT=http \
MCP_HTTP_PORT=443 \
MCP_BASE_URL=https://mcp.your-domain.com \
MCP_SSL_KEY_PATH=/etc/ssl/private/key.pem \
MCP_SSL_CERT_PATH=/etc/ssl/certs/cert.pem \
MCP_ENABLE_IP_ALLOWLIST=true \
SIRV_AI_BASE_URL=https://www.sirv.studio \
bun run start:http

2. 或使用反向代理（推荐）

nginx 配置示例：

server {
    listen 443 ssl http2;
    server_name mcp.your-domain.com;

    ssl_certificate /etc/ssl/certs/cert.pem;
    ssl_certificate_key /etc/ssl/private/key.pem;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

3. 在 claude.ai 中配置

部署完成后，用户可以在 claude.ai 的 MCP 设置中使用你的服务 URL 进行连接。

开发

# Run in development mode with auto-reload (stdio)
bun run dev

# Run in development mode (http)
bun run dev:http

# Build for production
bun run build

# Run the server (stdio)
bun run start

# Run the server (http)
bun run start:http

工具使用示例

移除背景

Remove the background from https://example.com/product.jpg

生成图像

Generate an image of a modern minimalist living room with natural lighting

浏览资源

Show me my latest 10 assets
Search my assets for "product photos"

管理产品

List all active products from Shopify
Create a product with SKU "CHAIR-001" named "Modern Chair"
Link these 3 assets to the chair product as gallery images

Shopify 工作流

Check my Shopify connection status
Sync products from Shopify including images
Push this processed image to Shopify product 12345

积分消耗

工具	积分
移除背景	1-2
放大	2-3
生成	2
图生图	2-4
替换背景	4
移除对象	3
替代文本	1
深度图	免费
虚拟试穿	4
图像转 3D	80
视频生成	可变

故障排除

连接问题

“找不到服务”或连接被拒绝

• 确认服务正在运行：stdio 模式使用 bun run start，HTTP 模式使用 bun run start:http
• 检查 SIRV_AI_BASE_URL 是否设置正确
• 使用 HTTP 模式时，确保端口未被防火墙阻止

“身份验证失败”

• 删除已存储的令牌：rm -rf ~/.sirv-ai/tokens.json
• 通过 OAuth 流程重新进行身份验证
• 确认你的账户在 https://www.sirv.studio 上处于有效状态

“API 密钥无效”

• 检查 SIRV_AI_API_KEY 是否设置正确（如果使用 API 密钥身份验证）
• 在 Sirv AI Studio 账户设置中重新生成 API 密钥

工具错误

“点数不足”

• 使用 sirv_get_usage 工具检查点数余额
• 在 https://www.sirv.studio/billing 购买更多点数

“无法访问图片 URL”

• 确保图片 URL 可公开访问（未受身份验证保护）
• 先尝试将图片上传到公开托管服务

“处理超时”

• 大图片或复杂操作可能需要更长时间
• 尝试使用更小的图片或更低的分辨率设置
• 视频生成和 3D 转换可能需要几分钟

HTTP 传输问题

浏览器中的 CORS 错误

• 将你的来源添加到 MCP_CORS_ORIGINS 环境变量
• 示例：MCP_CORS_ORIGINS="https://your-app.com,https://claude.ai"

SSL/TLS 证书错误

• 确认 MCP_SSL_KEY_PATH 和 MCP_SSL_CERT_PATH 中的证书路径正确
• 确保证书未过期
• 对于开发环境，可以考虑使用配置了 Let's Encrypt 的反向代理

IP 被阻止

• 如果使用 IP 允许列表，将你的 IP 添加到 MCP_ALLOWED_IPS
• 检查你的 IP 是否已更改（动态 IP 地址）

获取帮助

• 报告问题：https://www.sirv.studio/contact?type=support
• 文档：https://www.sirv.studio/docs
• 联系支持团队：[email protected]

隐私政策与服务条款

使用 Sirv AI MCP Server 即表示你同意我们的条款和政策：

• 隐私政策：https://www.sirv.studio/privacy
• 服务条款：https://www.sirv.studio/terms

数据处理

• 图片通过 fal.ai API 处理，并受其数据政策约束
• 生成的输出会临时存储，以便检索
• 用户身份验证令牌在本地存储于 ~/.sirv-ai/tokens.json
• 除身份验证所需的信息外，MCP 服务本身不会收集任何用户数据

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。