TravelAnimator

Travel Animator MCP

描述一次旅行，生成一段视频。

Travel Animator MCP 可让 AI 助手规划路线、设置动画风格，并在你的电脑上将其渲染为 MP4 视频——路线会随着行程逐步绘制，3D 载具沿路线行驶，同时显示地图标签、国旗，以及移动应用绘制的距离徽章。

你说： “为我制作一段 20 秒的视频，展现从里斯本经波尔图到布拉加的自驾游，使用 Terrain 地图、红色路线和一辆汽车。”

**你的助手：**创建项目，添加三个停靠点，沿它们之间的真实道路行驶，设置地图和路线样式，完成渲染，并返回 MP4 文件的路径。

更多可用提示词，以及它不会执行的操作，请参阅 examples/prompts.md。

---

安装

只需两条命令。第二条不可省略——基于 stdio 的 MCP 服务无法提示你输入凭据，因此你需要在自己的终端中登录一次。

Claude Code

claude mcp add travel-animator -e TADA_SOURCE=readme -- uvx --from "travel-animator[mcp]@latest" travel-animator mcp
uvx travel-animator login

Claude Desktop、Cursor、VS Code、Codex，或任何支持 JSON 配置的客户端

{
  "mcpServers": {
    "travel-animator": {
      "command": "uvx",
      "args": ["--from", "travel-animator[mcp]@latest", "travel-animator", "mcp"],
      "env": { "TADA_SOURCE": "readme" }
    }
  }
}

……然后在终端中运行 uvx travel-animator login。

@latest 会在每次启动时重新解析，因此只需重启客户端即可完成更新。 如果不加它，uvx 会复用首次缓存的版本，你也会一直停留在该版本。

TADA_SOURCE 用于告知我们你采用了哪套说明。此项为可选；如果愿意，可以删除。

已经安装 Python？ 运行 pip install "travel-animator[mcp]"，并将 travel-animator 用作 command。需要 Python 3.12 或更高版本。

各客户端的说明，包括“在终端中可用、但在桌面应用中不可用”时的 PATH 修复方法，请参阅 docs/clients.md。

所需条件

Python	3.12 或更高版本
账号	与移动应用相同的 Travel Animator 账号。免费账号可以登录、浏览目录并创作项目，但只有高级账号才能渲染项目。
平台	macOS（Apple silicon）、Linux（x86-64、arm64）、Windows（x64）。目前发布了这四种平台的 wheel；其他平台——包括 Intel macOS——均不受支持。
磁盘	wheel 约为 85 MB。它自带 Java 运行时，在 macOS 和 Windows 上还自带图形驱动——无需另行安装。Linux 使用系统 GLES 驱动，或使用 Mesa 进行软件渲染。
网络	渲染无法离线进行：绘制帧时会获取地图切片、字形和精灵图，然后缓存到 ~/.cache/tada/render 下。

如果你的设备完全无法渲染，服务会在你创建无法完成的项目之前明确告知，并可改用服务端渲染。

可生成的内容

• 34 种地图样式——Terrain、Satellite、Sketch、Glow、Comic、Winter、Pixel、Watercolor 等（list_maps）。其中一种免费，其余需要高级账号。
• 355 个 3D 模型——涵盖陆地、空中和水上模型，从写实汽车和飞机到大象（list_models）。其中 11 个免费。
• 7 种路线样式——实线、虚线、点线、条纹、发光、透明、自动（list_line_styles）。
• 两种投影——平面 MERCATOR，或带星星、太阳和月亮的 3D GLOBE。
• 9–60 秒的视频，可自行选择宽高比和分辨率。
• 每个路段均可选择真实道路或直线。
• 地点标签、国旗、距离徽章、头像和逐点特效。

工作原理

create_project → create_route → update_animation_state → render_video → await_render → MP4

有两点值得了解，因为它们会影响助手的行为：

• 不会隐式编辑任何内容。 每个工具都需要明确指定 project_id。没有“当前项目”，因此助手可以同时打开多个行程而不会混淆。
• 项目是持久化的本地状态，位于 $XDG_STATE_HOME/tada-render/projects/<id>/（如果未设置，则位于 ~/.local/state/…）。视频会保存到相应项目的 renders/ 目录中；每个项目保留最新的五个视频，并清理更早的视频。关闭助手后，项目明天仍会保留。

工具

共 30 个工具。完整参数参考见 docs/tools.md。

分组	工具
先检查	get_capabilities · auth_status
项目	create_project · list_projects · get_project · delete_project · import_project · export_project
路线	create_route · get_route · add_point · update_point · remove_point · clear_route · set_real_route
外观与风格	get_animation_state · update_animation_state · list_maps · list_models · list_line_styles
渲染	estimate_render · render_video · await_render · get_render_progress · get_render_result · cancel_render
账户同步	list_account_routes · save_project_to_account · load_account_route · delete_account_route

渲染过程中会持续报告进度。 render_video 会立即返回一个会话 ID；await_render 会等待该会话，如果渲染仍在进行，则会返回一行供助手读出的信息——已完成的帧数、百分比、剩余时间——然后继续等待。渲染十分钟，不代表要沉默十分钟。

路线会同步到手机。 save_project_to_account 会将路线保存到移动应用的“已保存路线”中。它只会保留航点——回复中的 dropped 列表会列出未能保留的内容（头像、特效、额外模型槽位、本地媒体、动画设置），助手应将这些情况告知你，而不是声称保存成功且毫无遗漏。

隐私政策

完整政策涵盖应用、网站和此软件包，详见 travelanimator.com/privacy-policy；其中有专门介绍 MCP 服务和 CLI 的章节。以下是该章节的简要说明。

使用情况分析需要主动选择加入，默认关闭。启用前不会收集任何信息，MCP 服务之外也不会收集任何信息。

travel-animator analytics status   # what is set, and what it covers
travel-animator analytics on       # grant consent
travel-animator analytics off      # revoke, effective immediately

无论你是否同意，都绝不会收集： 路线坐标、地点标签、路线注释、文件路径、你的媒体、任何已保存或加载路线的内容、你为项目指定的名称，以及工具返回的内容。路线记录的是某人实际到过的地方。

经你同意后收集： 调用了哪些工具、调用顺序、耗时及是否失败；渲染设置（分辨率、时长、动画风格、地图、载具）；路线中的点数，以及路线所经过的国家集合。

一项自由文本例外： 当助手请求此服务不具备的工具时，它描述自己尝试执行什么操作的句子会随该请求一并收集（最多 2048 个字符）——这是服务了解自己缺少哪项功能的唯一方式。此信息绝不会附加到普通工具调用中。分析数据由第三方服务提供商在美国处理。

命令行

MCP 服务是两种前端之一，另一种是 CLI：

travel-animator login           # log in: magic link, or a bearer token for CI
travel-animator logout          # remove credentials stored on this machine
travel-animator analytics       # show, grant or revoke analytics consent
travel-animator render-bundle   # render a prepared render bundle to MP4
travel-animator mcp             # run the MCP server (needs the mcp extra)

render-bundle 用于渲染由 Travel Animator 服务生成的捆绑包；它不会创建捆绑包。MCP 服务是唯一能从零开始生成成品视频的途径。

故障排查

症状	原因	解决方法
工具提示“登录”消息后失败	此计算机上没有凭据，或凭据已过期	在终端中运行 travel-animator login，然后重试
登录成功，但渲染被拒绝	使用的是免费账户	渲染需要高级版
MCP 服务无法从桌面应用启动	GUI 应用不会继承 shell 的 PATH	使用 which uvx 输出的绝对路径
在 Mac 上运行 pip install 失败	Intel macOS 没有对应的 wheel	仅支持 Apple silicon、Linux 或 Windows
在没有 GPU 的计算机上渲染失败	没有可用的 GL	先调用 get_capabilities；使用服务端回退方案
第二次渲染被拒绝	每个项目和每个进程一次只能渲染一个任务	等待，或调用 cancel_render

更多信息（包括错误代码），请参阅 docs/troubleshooting.md。

支持

请提交 issue——请注明你的操作系统、travel-animator --version、你的 MCP 客户端、失败的工具以及对应的 error_code。也可以发送邮件至 [email protected]。

许可证

这不是开源软件。 travel-animator 包采用有限使用许可证：你可以安装并运行未经修改的软件包，以准备和渲染 Travel Animator 内容，并与 Lascade 的服务通信。你不得重新分发或修改该软件包，也不得使用它构建竞争服务。完整条款随软件包一同提供，位于 tada_render/LICENSE。

渲染器中捆绑的字体、旗帜图稿和库均为受各自许可证约束的第三方作品，许可证列表见 tada_render/THIRD-PARTY-NOTICES.md。如需重新分发或修改相关内容，请联系 Lascade。

本仓库中的 文档和示例采用 MIT 许可证——请参阅 LICENSE。

---

PyPI · travelanimator.com · 隐私政策 · iOS · Android