MCP Server for Autodesk ShotGrid REST API

Autodesk ShotGrid REST API 的 MCP 服务

此项目提供一个使用 FastMCP 实现的 MCP（Model Context Protocol）服务，使大模型（LLM）Agent 能够通过 Autodesk ShotGrid REST API 以编程方式与其交互。它提供一组工具，用于查询和管理 ShotGrid 实体，例如项目、资产、任务、用户、备注等。该服务支持 transport="stdio" 模式，可集成到基于大模型的工作流中。

功能

• 使用 OAuth2 身份验证连接到 Autodesk ShotGrid。
• 使用 FastMCP 将 ShotGrid REST API 操作作为 MCP 工具提供。
• 查询项目、用户、资产、任务、备注、版本、预订等。
• 获取实体的详细信息。
• 专为集成到基于大模型的工作流中而设计。
• 模块化代码库：main.py 提供 MCP 服务和核心工具定义；booking_tools.py 处理所有 Booking CRUD 操作；note_tools.py 处理 Note / Reply CRUD 操作以及附件读取；shotgrid_rest.py 实现 ShotGrid API 封装。

要求

• Python 3.11
• httpx
• httpx-auth
• mcp.server.fastmcp

安装

1. 克隆代码仓库：

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

2. 如果尚未安装 uv，请先安装。 uv 会自动管理 Python 3.11 和 pyproject.toml 中声明的依赖项；无需手动创建 venv。

3. 配置凭据。 使用环境变量（推荐）或 CLI 参数。请参阅用法。

4. 在 MCP 客户端中注册服务。 Claude Code 的示例（~/.claude.json 或项目本地的 .mcp.json）：

   {
     "mcpServers": {
       "shotgrid": {
         "command": "uv",
         "args": ["run", "--directory", "D:\\path\\to\\mcp-server-shotgrid", "main.py"],
         "env": {
           "SHOTGRID_HOST": "https://your-shotgrid-url",
           "SHOTGRID_CLIENT_ID": "your_client_id",
           "SHOTGRID_CLIENT_SECRET": "your_client_secret"
         }
       }
     }
   }
   

用法

凭据可以通过**环境变量（推荐）**或 CLI 参数提供。环境变量优先；如果这三项中的任意一项缺失，服务就会报错退出。

选项 A — 环境变量（推荐）

变量	描述
SHOTGRID_HOST	ShotGrid 主机 URL，例如 https://your-shotgrid-url
SHOTGRID_CLIENT_ID	OAuth2 客户端 ID
SHOTGRID_CLIENT_SECRET	OAuth2 客户端密钥

Windows（PowerShell）：

$env:SHOTGRID_HOST = "https://your-shotgrid-url"
$env:SHOTGRID_CLIENT_ID = "your_client_id"
$env:SHOTGRID_CLIENT_SECRET = "your_client_secret"
uv run --directory C:\path\to\mcp-server-shotgrid main.py

macOS / Linux（bash / zsh）：

export SHOTGRID_HOST="https://your-shotgrid-url"
export SHOTGRID_CLIENT_ID="your_client_id"
export SHOTGRID_CLIENT_SECRET="your_client_secret"
uv run --directory /path/to/mcp-server-shotgrid main.py

选项 B — CLI 参数

uv run --directory {REPO_DIR} main.py --host https://your-shotgrid-url --client-id your_client_id --client-secret your_client_secret

短格式（-host、-ci、-cs）和长格式（--host、--client-id、--client-secret）均受支持。

安全提示

优先使用环境变量，而不是 CLI 参数。通过命令行传递的参数会显示在进程列表（ps、任务管理器）、Shell 历史记录以及许多主管程序/IDE 配置文件中。环境变量可以降低意外泄露的风险，但它们仍属于机密信息——请将其存储在受保护的配置文件中（例如 .mcp.json / ~/.claude.json），使用严格的文件权限，并且切勿将机密信息提交到版本控制系统。

该服务使用 FastMCP，且仅通过 transport="stdio" 通信。MCP 提供的工具可供大模型 Agent 调用。

可用工具

所有工具均为异步工具，并通过 FastMCP 提供。它们会返回结构化的 Python 对象（List 或 Dict），并由 MCP 框架自动序列化。括号中的参数均为必填项，除非标记为可选。

• get_all_projects()：列出所有项目。
• get_all_users()：列出所有用户。
• get_all_projects_field_contains(value: str, field: str = "name")：列出字段包含指定值的项目。
• get_sequences(project_id: int (optional), project_name: str (optional), code: str (optional), updated_in_last_n_days: int (optional), updated_date_from: [YYYY,MM,DD] (optional), updated_date_to: [YYYY,MM,DD] (optional))：列出镜头序列，可按项目、代码或日期筛选。
• get_shots(project_id: int (optional), project_name: str (optional), sequence_id: int (optional), sequence_code: str (optional), shot_code: str (optional), updated_in_last_n_days: int (optional), updated_date_from: [YYYY,MM,DD] (optional), updated_date_to: [YYYY,MM,DD] (optional))：列出镜头，支持多种筛选条件。
• get_assets(project_id: int (optional), project_name: str (optional), code: str (optional), updated_in_last_n_days: int (optional), updated_date_from: [YYYY,MM,DD] (optional), updated_date_to: [YYYY,MM,DD] (optional))：列出资产，可选择性地使用筛选条件。
• get_tasks(entity_type: str (optional), entity_id: int (optional), project_id: int (optional), project_name: str (optional), user_id: int (optional), task_name: str (optional), updated_in_last_n_days: int (optional), updated_date_from: [YYYY,MM,DD] (optional), updated_date_to: [YYYY,MM,DD] (optional))：列出任务，可选择性地使用筛选条件。
• get_users_name_or_login_contains(name: str (optional), login: str (optional))：列出姓名或登录名包含指定子字符串的用户。
• get_notes(shot_id: int (optional), asset_id: int (optional), user_id: int (optional), task_id: int (optional), version_id: int (optional), project_id: int (optional), project_name: str (optional), task_name: str (optional), asset_code: str (optional), version_name: str (optional), updated_in_last_n_days: int (optional), updated_date_from: [YYYY,MM,DD] (optional), updated_date_to: [YYYY,MM,DD] (optional), limit: int (optional), page: int (optional))：列出备注，支持全面的筛选选项。支持通过 limit / page 分页，避免大型项目被 ShotGrid 的默认分页限制而静默截断。
• create_note(content: str, project_id: int, subject: str (optional), link_shot_ids: [int] (optional), link_asset_ids: [int] (optional), link_task_ids: [int] (optional), link_version_ids: [int] (optional), task_ids: [int] (optional), addressing_to_user_ids: [int] (optional), addressing_cc_user_ids: [int] (optional), user_id: int (optional), sg_status_list: str (optional))：创建新备注。note_links 由四个 link_* 列表构建。若未提供 user_id，则默认为 API 用户。
• update_note(note_id: int, content: str (optional), subject: str (optional), sg_status_list: str (optional), link_shot_ids: [int] (optional), link_asset_ids: [int] (optional), link_task_ids: [int] (optional), link_version_ids: [int] (optional), task_ids: [int] (optional), addressing_to_user_ids: [int] (optional), addressing_cc_user_ids: [int] (optional))：更新现有备注。提供多实体列表参数时会替换现有值（传入 [] 可清除）。无法通过更新更改 project 和 user。
• delete_note(note_id: int)：按 ID 删除备注。
• get_replies(note_id: int, limit: int (optional), page: int (optional))：列出备注下的回复，并返回完整回复字段（content、user、entity、时间戳、attachments）。支持通过 limit / page 分页。此工具取代了之前的 get_all_replies_with_note_id，后者仅返回 ID。
• create_reply(content: str, note_id: int, user_id: int (optional))：在备注下发布回复。若未提供 user_id，则默认为 API 用户。
• update_reply(reply_id: int, content: str)：更新回复内容。
• delete_reply(reply_id: int)：按 ID 删除回复。
• get_note_attachments(note_id: int)：列出备注上的附件引用（轻量格式 [{id, type, name}]）。
• get_attachment_info(attachment_id: int)：获取完整的附件元数据（this_file URL、image 缩略图、显示名称、内容类型、大小）。
• get_versions(project_id: int (optional), project_name: str (optional), task_id: int (optional), task_name: str (optional), user_id: int (optional), updated_in_last_n_days: int (optional), updated_date_from: [YYYY,MM,DD] (optional), updated_date_to: [YYYY,MM,DD] (optional))：列出版本，可选择性地使用筛选条件。
• get_bookings(user_ids: [int] (optional), project_ids: [int] (optional), range_from: [YYYY,MM,DD] (optional), range_to: [YYYY,MM,DD] (optional), vacation: bool (optional), exclude_vacation: bool (optional), sg_status_list: "cfrm"|"pndng" (optional), sort_field: "start_date"|"end_date"|"updated_at" (default "start_date"), sort_order: "asc"|"desc" (default "asc"), limit: int (optional), page: int (optional))：列出日期区间与 [range_from, range_to] 重叠的预订。支持通过 in 关系查询多个用户和多个项目。v0.2.0 中的破坏性变更：user_id / project_id 已替换为列表值参数 user_ids / project_ids；四个参数 start_date_from/to / end_date_from/to 已替换为 range_from / range_to，并采用包含边界的重叠语义。
• create_booking(user_id: int, project_id: int, start_date: [YYYY,MM,DD], end_date: [YYYY,MM,DD], vacation: bool (optional), note: str (optional), percent_allocation: float (optional), sg_status_list: "cfrm"|"pndng" (optional))：创建新的预订。
• update_booking(booking_id: int, start_date: [YYYY,MM,DD] (optional), end_date: [YYYY,MM,DD] (optional), vacation: bool (optional), note: str (optional), percent_allocation: float (optional), sg_status_list: "cfrm"|"pndng" (optional))：更新现有预订。注意：无法通过更新更改 user 和 project；如需更改，请删除并重新创建预订。
• delete_booking(booking_id: int)：按 ID 删除预订。
• get_entities_updated_in_last_n_days(entity_type: str, n: int, project_id: int (optional))：列出过去 n 天内更新过的指定类型实体。
• get_entity_by_id(entity_type: str, entity_id: int)：按类型和 ID 获取实体详情。

错误处理

该服务包含一个健壮的错误处理包装器，可捕获 ShotGrid API 错误和内部异常，并将其作为包含 error 和 message 字段的结构化 JSON 对象返回。

说明

• 确保你的 ShotGrid 账户已启用 API 访问权限。
• 该服务使用 OAuth2 进行身份验证。
• 该服务使用 FastMCP 实现，且仅使用 transport="stdio" 运行。
• 可通过环境变量（SHOTGRID_HOST、SHOTGRID_CLIENT_ID、SHOTGRID_CLIENT_SECRET）或 CLI 参数（-host / --host、-ci / --client-id、-cs / --client-secret）提供凭据。环境变量优先。
• 某些工具会动态获取字段，并排除特定键（参见 main.py 中的 remove_exclude_fields）。
• 可根据需要扩展或自定义 main.py 中的工具，以适应你的工作流。
• ShotGrid REST API 的逻辑在 shotgrid_rest.py 中实现。

许可证

MIT 许可证