射击网格-MCP服务器

Name: 射击网格-MCP服务器
Author: loonghao

作者：loonghao30 星标更新：2025-11-23

安装使用来源：spider==github.com

项目介绍

技术文档摘要

🎯 ShotGrid MCP Server

简体中文 | English

基于 fastmcp 的高性能 ShotGrid 模型上下文协议（MCP）服务器实现。

</div>

🎬 示例

这是一个使用 ShotGrid MCP 服务器查询实体的简单示例：

ShotGrid MCP Server 示例

✨ 功能

🚀 基于 fastmcp 的高性能实现
🛠 完整的 CRUD 操作工具集
🖼 专用缩略图下载/上传工具
🔄 高效的连接池管理
🔌 通过 MCP 工具直接访问 ShotGrid API
📝 增强的笔记和播放列表管理
🌐 多种传输模式：stdio、HTTP 和 ASGI
☁️ 云就绪的 ASGI 应用程序，便于部署
🔧 支持自定义中间件（如 CORS、认证等）
✅ 使用 pytest 进行全面测试覆盖
📦 使用 UV 管理依赖项
🌐 跨平台支持（Windows、macOS、Linux）

🚀 快速开始

安装

使用 UV 安装：

uv pip install shotgrid-mcp-server

快速使用

安装后，可以直接启动服务器：

STDIO 传输（默认）

对于本地 MCP 客户端（如 Claude Desktop、Cursor 等）：

uvx shotgrid-mcp-server

这将使用 stdio 传输启动 ShotGrid MCP 服务器，这是本地 MCP 客户端的默认模式。

HTTP 传输

对于基于 Web 的部署或远程访问：

# 在默认端口（8000）上启动 HTTP 传输
uvx shotgrid-mcp-server http

# 启动自定义主机和端口
uvx shotgrid-mcp-server http --host 0.0.0.0 --port 8080

# 启动自定义路径
uvx shotgrid-mcp-server http --path /api/mcp

HTTP 传输使用可流式传输的 HTTP 协议，推荐用于 Web 部署，并允许远程客户端连接到您的服务器。

多站点支持（HTTP 传输）

HTTP 传输模式支持通过 HTTP 请求头配置 ShotGrid 凭证，使单个服务器实例能够服务于多个 ShotGrid 站点：

服务器配置：

# 设置默认环境变量（服务器启动所需）
export SHOTGRID_URL="https://default.shotgunstudio.com"
export SHOTGRID_SCRIPT_NAME="default_script"
export SHOTGRID_SCRIPT_KEY="default_key"

# 启动 HTTP 服务器
uvx shotgrid-mcp-server http --host  0.0.0.0 --port 8000

客户端配置：

在您的 MCP 客户端配置中，为每个 ShotGrid 站点添加自定义 HTTP 头：

{
  "mcpServers": {
    "shotgrid-site-1": {
      "url": "http://your-server:8000/mcp",
      "transport": {
        "type": "http",
        "headers": {
          "X-ShotGrid-URL": "https://site1.shotgunstudio.com",
          "X-ShotGrid-Script-Name": "my_script",
          "X-ShotGrid-Script-Key": "abc123..."
        }
      }
    },
    "shotgrid-site-2": {
      "url": "http://your-server:8000/mcp",
      "transport": {
        "type": "http",
        "headers": {
          "X-ShotGrid-URL": "https://site2.shotgunstudio.com",
          "X-ShotGrid-Script-Name": "another_script",
          "X-ShotGrid-Script-Key": "xyz789..."
        }
      }
    }
  }
}

这允许您在同一 MCP 客户端中配置多个 ShotGrid 站点实例，每个站点具有不同的凭证。

注意：

对于 stdio 传输模式，仍然需要环境变量（SHOTGRID_URL、SHOTGRID_SCRIPT_NAME、SHOTGRID_SCRIPT_KEY）
对于 HTTP 传输模式，可以通过 HTTP 头传递凭证，也可以使用环境变量作为默认值
推荐在生产环境中使用 HTTPS 来保护 API 密钥

ASGI 部署

对于生产部署，您可以使用任何 ASGI 服务器独立部署 ASGI 应用程序。

注意：ASGI 应用程序使用延迟初始化——仅在收到第一个请求时创建 ShotGrid 连接，而不是在模块导入期间。这可以防止在 Docker 构建或应用程序启动期间出现连接错误。

# 开发模式使用 Uvicorn
uvicorn shotgrid_mcp_server.asgi:app --host 0.0.0.0 --port 8000 --reload

# 生产模式使用多个工作进程
uvicorn shotgrid_mcp_server.asgi:app --host 0.0.0.0 --port 8000 --workers 4

# 使用 Gunicorn 和 Uvicorn 工作进程（推荐用于生产）
gunicorn shotgrid_mcp_server.asgi:app \
    -k uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000 \
    --workers 4

# 使用 Hypercorn
hypercorn shotgrid_mcp_server.asgi:app --bind 0.0.0.0:8000

带有中间件的自定义 ASGI 应用程序：

创建一个自定义的 app.py 文件：

from starlette.middleware import Middleware
from starlette.middleware.cors import CORSMiddleware
from shotgrid_mcp_server.asgi import create_asgi_app

# 为您的域配置 CORS
cors_middleware = Middleware(
    CORSMiddleware,
    allow_origins=["https://yourdomain.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)

# 创建带有中间件的应用程序
app = create_asgi_app(
    middleware=[cors_middleware],
    path="/mcp"
)

然后进行部署：

uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4

云平台部署：

ASGI 应用程序可以轻松部署到以下云平台：

FastMCP Cloud
AWS Lambda（使用 Mangum）
Google Cloud Run
Azure Container Apps
Heroku
Railway
Render

详细说明请参阅部署指南。

开发设置

克隆仓库：

git clone https://github.com/loonghao/shotgrid-mcp-server.git
cd shotgrid-mcp-server

安装开发依赖项：

pip install -r requirements-dev.txt

开发命令所有开发命令都通过 nox 管理。检查 noxfile.py 中可用的命令：

# 运行测试
nox -s tests

# 运行代码检查
nox -s lint

# 运行类型检查
nox -s type_check

# 更多...

开发服务器与热重载

注意：这需要在系统上安装 Node.js。

为了获得更好的开发体验（服务器会在代码更改时自动重启）：

uv run fastmcp dev src/shotgrid_mcp_server/server.py:app

这将以开发模式启动服务器，任何代码更改都会自动重新加载服务器。

⚙️ 配置

环境变量

需要以下环境变量：

SHOTGRID_URL=your_shotgrid_url
SHOTGRID_SCRIPT_NAME=your_script_name
SHOTGRID_SCRIPT_KEY=your_script_key

您可以在您的 shell 中直接设置它们：

# PowerShell
$env:SHOTGRID_URL='your_shotgrid_url'
$env:SHOTGRID_SCRIPT_NAME='your_script_name'
$env:SHOTGRID_SCRIPT_KEY='your_script_key'

# Bash
export SHOTGRID_URL='your_shotgrid_url'
export SHOTGRID_SCRIPT_NAME='your_script_name'
export SHOTGRID_SCRIPT_KEY='your_script_key'

或者在项目目录中创建一个 .env 文件。

🔧 可用工具

核心工具

create_entity: 创建 ShotGrid 实体
find_one_entity: 查找单个实体
search_entities: 使用过滤器搜索实体
update_entity: 更新实体数据
delete_entity: 删除实体

媒体工具

download_thumbnail: 下载实体缩略图
upload_thumbnail: 上传实体缩略图

笔记与播放列表工具

shotgrid.note.create: 创建笔记
shotgrid.note.read: 读取笔记信息
shotgrid.note.update: 更新笔记内容
create_playlist: 创建播放列表
find_playlists: 使用过滤器查找播放列表

直接 API 访问

sg.find: 直接访问 ShotGrid API 的 find 方法
sg.create: 直接访问 ShotGrid API 的 create 方法
sg.update: 直接访问 ShotGrid API 的 update 方法
sg.batch: 直接访问 ShotGrid API 的 batch 方法
更多...

🤖 AI 提示示例

这里有一些如何使用 ShotGrid MCP 与 AI 助手（如 Claude）交互的例子：

基本查询

帮我找到过去三个月内更新的所有 ShotGrid 实体。

显示上周更新的所有“Awesome Project”镜头。

创建和管理播放列表

创建一个名为“每日回顾 - 4月21日”的播放列表，包含昨天由灯光部门更新的所有镜头。

查找本周创建的所有播放列表。

笔记和反馈

给 SHOT_010 添加一条注释：“请调整背景中的灯光以增加戏剧性。”

高级工作流程

帮助我总结本月“动画”部门的时间记录，并使用 echarts 生成图表来可视化所花费的小时数。

查找昨天由灯光团队更新的所有镜头，创建一个名为“灯光审查 - 4月21日”的播放列表，并通过注释通知导演。

📚 文档

详细的文档，请参阅 /docs 目录中的文档文件。

您还可以在安装服务器后，在 Claude Desktop 中直接探索可用工具及其参数。

🤝 贡献

欢迎贡献！请确保：

遵循 Google Python 编码规范
使用 pytest 编写测试
更新文档
使用绝对导入
遵循项目的编码标准

📝 版本历史

详细版本历史，请参阅 CHANGELOG.md。

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

🔌 MCP 客户端配置

要在您的 MCP 客户端中使用 ShotGrid MCP 服务器，请在客户端设置中添加适当的配置。

Claude Desktop / Anthropic Claude

{
  "mcpServers": {
    "shotgrid-server": {
      "command": "uvx",
      "args": [
        "--python", "3.10",
        "shotgrid-mcp-server"
      ],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "XXX",
        "SHOTGRID_SCRIPT_KEY": "XX",
        "SHOTGRID_URL": "XXXX"
      },
      "disabled": false,
      "alwaysAllow": [
        "search_entities",
        "create_entity",
        "batch_create",
        "find_entity",
        "get_entity_types",
        "update_entity",
        "download_thumbnail",
        "batch_update",
        "delete_entity",
        "batch_delete"
      ]
    }
  }
}

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "shotgrid-server": {
      "command": "uvx",
      "args": [
        "shotgrid-mcp-server"
      ],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "XXX",
        "SHOTGRID_SCRIPT_KEY": "XX",
        "SHOTGRID_URL": "XXXX"
      }
    }
  }
}

Windsurf (Codeium)

// MCP 配置
{
  "mcpServers": {
    "shotgrid-server": {
      "command": "uvx",
      "args": [
        "shotgrid-mcp-server"
      ],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "XXX",
        "SHOTGRID_SCRIPT_KEY": "XX",
        "SHOTGRID_URL": "XXXX"
      }
    }
  }
}

Cline (VS Code 扩展)

// MCP 配置
{
  "mcpServers": {
    "shotgrid-server": {
      "command": "uvx",
      "args": [
        "shotgrid-mcp-server"
      ],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "XXX",
        "SHOTGRID_SCRIPT_KEY": "XX",
        "SHOTGRID_URL": "XXXX"
      }
    }
  }
}

Visual Studio Code

// .vscode/mcp.json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "shotgrid-script-name",
      "description": "ShotGrid 脚本名称",
      "password": false
    },
    {
      "type": "promptString",
      "id": "shotgrid-script-key",
      "description": "ShotGrid 脚本密钥",
      "password": true
    },
    {
      "type": "promptString",
      "id": "shotgrid-url",
      "description": "ShotGrid URL",
      "password": false
    }
  ],
  "servers": {
    "shotgrid-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["shotgrid-mcp-server"],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "${input:shotgrid-script-name}",
        "SHOTGRID_SCRIPT_KEY": "${input:shotgrid-script-key}",
        "SHOTGRID_URL": "${input:shotgrid-url}"
      }
    }
  }
}

VS Code 用户设置

// settings.json
{
  "mcp": {
    "shotgrid-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["shotgrid-mcp-server"],
      "env": {
        "SHOTGRID_SCRIPT_NAME": "XXX",
        "SHOTGRID_SCRIPT_KEY": "XX",
        "SHOTGRID_URL": "XXXX"
      }
    }
  },
  "chat.mcp.discovery.enabled": true
}

🔑 凭证设置

在上述配置示例中，替换以下值为您自己的 ShotGrid 凭证：

SHOTGRID_SCRIPT_NAME: 您的 ShotGrid 脚本名称
SHOTGRID_SCRIPT_KEY: 您的 ShotGrid 脚本密钥
SHOTGRID_URL: 您的 ShotGrid 服务器 URL

🛡️ 工具权限

alwaysAllow 部分列出了无需用户确认即可执行的工具。这些工具经过精心选择以确保安全操作。您可以根据安全需求自定义此列表。