truetick-gg

TrueTick MCP 服务

通过 AI Agent 直接管理 TrueTick Minecraft 服务。此 MCP 服务向 Claude 和其他兼容的 AI 客户端提供 30 个工具，涵盖 TrueTick 公共 API 中面向服务端的功能，包括生命周期、控制台、指标和 tick 历史记录、文件、备份、模组、模板和钱包。

它并非完整 API：公共接口共有 98 项操作。这里完全没有网络、容量和区域相关工具；而在账户级操作中，仅支持钱包（get_wallet），不支持账本、账户限额和结账链接。如需使用这些功能，请直接调用 REST API。

安装与设置

1. 获取 API 密钥

访问 truetick.gg/dashboard/api-keys 创建 API 密钥。选择所需的作用域（例如 servers:read、servers:write、billing:read）。

2. 配置 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中（Windows：%APPDATA%\Claude\claude_desktop_config.json；Mac：~/Library/Application Support/Claude/claude_desktop_config.json；Linux：~/.config/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "truetick": {
      "command": "npx",
      "args": ["-y", "@truetick/mcp"],
      "env": {
        "TRUETICK_API_KEY": "ttk_your_key_here"
      }
    }
  }
}

将 ttk_your_key_here 替换为你的实际 API 密钥。

3. 配置

MCP 服务从环境变量读取配置：

• TRUETICK_API_KEY（必填）：具有相应作用域的 TrueTick API 密钥。
• TRUETICK_API_URL（可选，默认为 https://api.truetick.gg）：API 端点。可覆盖此值，以便针对其他环境进行测试。

工具目录

账户与钱包

• whoami — 显示 API 密钥所绑定的账户。
• list_servers — 列出你的所有 Minecraft 服务。
• get_wallet — 显示你的钱包余额和近期交易。

服务管理

• create_server — 创建新的 Minecraft 服务（指定名称、RAM、服务端类型、版本、区域和计费方案）。
• get_server — 获取指定服务的详细信息。
• start_server — 启动已停止的服务。
• stop_server — 停止正在运行的服务。
• restart_server — 重启正在运行的服务。
• delete_server — 永久删除服务及其所有数据。
• update_server_version — 更改服务端类型和／或版本（服务必须处于停止状态）。
• set_server_properties — 更新 server.properties 中的键，并可选设置空闲超时。
• set_server_motd — 设置服务端的每日消息（MOTD）。
• list_templates — 列出可用于创建服务的模板（预设）。
• create_server_from_template — 根据模板预设创建服务。

控制台与指标

• run_command — 在正在运行的服务上执行控制台（RCON）命令。
• get_server_metrics — 获取服务实时 TPS/MSPT/玩家数量指标。读取 tps 时，请结合 tpsSource 一并查看：TPS_SOURCE_UNSPECIFIED 表示没有读数，而不是性能为零。
• get_server_tick_history — 以一分钟为单位汇总 tick 健康状况（默认 24h，最多 720 个）。服务休眠期间的分钟不会有任何记录——缺口就是真实缺口，绝不表示数值为零。
• get_recent_logs — 获取服务容器最近的日志行（快照）。

文件管理

• list_files — 列出服务上某个目录中的文件。
• read_file — 读取服务上的文件内容。
• write_file — 将内容写入服务上的文件。
• delete_file — 删除服务上的文件。

备份

• create_backup — 按需创建服务备份。
• list_backups — 列出服务可用的备份。
• restore_backup — 恢复备份（服务必须处于停止状态；将覆盖当前数据）。
• set_backup_kept — 保留备份（kept: true），使其不参与轮换，直到取消保留；或将其放回轮换（kept: false）。每个服务最多保留 3 个；保留的备份会占用服务的备份空间。

模组与插件

• list_mods — 列出服务器上已安装的模组/插件。
• add_mod — 从 Modrinth 或 CurseForge 添加模组或插件。
• list_mod_versions — 列出此服务器可固定使用的模组或插件构建版本（仅限其加载器和 Minecraft 版本，包含预发布版本）；将其中一个作为 version 传递给 add_mod。
• remove_mod — 从服务器移除模组或插件。

开发

npm run build      # Compile TypeScript
npm test           # Run tests
npm start          # Run the MCP server (for manual testing)

许可证

MIT — 参见 LICENSE。

关于此仓库

TrueTick 的开发在私有单体仓库中进行；此仓库镜像了已发布的 @truetick/mcp 版本。欢迎在此提交问题和参与讨论；如需贡献代码，请先在 issue 中提出更改建议。

相关链接：TypeScript SDK 和 CLI · 开发者文档 · truetick.gg/developers