Civ6 MCP Server

关键词

Civ6会话管理资源与工具管理日志与地图追踪火 tuner 集成

使用说明（简要、易操作版）

  • 项目简介

    • Civ6 MCP Server 是一个完整的后台服务器，专门把文明6的游戏信息通过 MCP 标准暴露给各类 LLM 客户端（如 Claude Code、Codex、Gemini CLI 等）。它实现了资源托管、工具执行、提示（Prompts）渲染等核心能力，并通过 JSON-RPC 形式和客户端通信。服务器端负责会话管理、能力声明、以及安全/可扩展的上下文服务框架。附带网页仪表盘、 diary/空间追踪等辅助组件，方便分析和调试。

  • 主要功能点

    • MCP 核心协议支持：通过 stdio 的 MCP 端口接收请求，执行相应的工具，并返回规范的 JSON-RPC 响应。 -resources/tools/prompts：托管资源、注册工具、渲染并提供可自定义的 Prompt 模板，支持多种交互模式。
    • Civ6 FireTuner 集成：服务器与 Civ6 的 FireTuner 协议对接，生成 Lua 代码在游戏中执行，并解析返回。
    • 会话与能力声明：服务器维护会话信息、能力声明，确保多客户端环境下的并发与隔离。
    • 多传输与扩展：支持标准 IO 传输（stdio），并在服务器上内置 Web API、日记、地图快照等扩展，用于可观测性与分析。
    • 背景服务与工具：地图快照、空间追踪、日记记录、日志系统，以及对 UI/弹窗进行观测/处理的辅助工具。
    • 运行与测试：内置 runner、测试连接、以及多场景的示例用法，便于本地验证。

  • 安装与运行（简要步骤）

    1. 克隆仓库
    2. 安装并使用 uv（Astral 的 uv 库）作为运行后端的入口工具
    3. 以 CP/MCP 的入口启动服务器（下述示例配置给出具体启动参数格式）
    4. 启动 Civ6（确保 FireTuner 启用并能连接到端口 4318）
    5. 使用 MCP 客户端连接服务器，开始对 Civ6 的对话式控制和上下文服务

  • 服务器配置（MCP 客户端需要的启动信息） 下面给出一个准确的服务器启动配置示例，便于 MCP 客户端（Claude Code、Codex、Gemini 等）通过配置文件连接到服务器。请将 path/to/civ6-mcp 替换为仓库实际所在路径。

    { "server_name": "civ6", "command": "uv", "args": ["run", "--directory", "/path/to/civ6-mcp", "civ-mcp"], "notes": "启动 Civ6 MCP 服务器的命令。服务器通过 stdio 与客户端通信，并在后台启动了网页仪表盘、 diary、地图捕获等服务。" }

    说明

    • server_name: 服务器的标识名称，便于客户端在多服务器场景下区分。
    • command 与 args: MCP 服务器的启动命令与参数。本仓库的服务器入口通过 uv run --directory <仓库路径> civ-mcp 启动。
    • 备注字段（notes）仅作说明用途，帮助理解连接方式与后台服务。

  • 基本使用方式

    • 客户端连接后，可以调用如 get_game_overview、get_units、get_map_area、end_turn 等工具，获得游戏状态并下达指令。
    • 服务器还内置了网页仪表盘（http://localhost:8000/）用于查看当前游戏状态和观测数据，便于调试与分析。
    • 日记、空间追踪、地图快照等工具用于记录和回放，帮助评测与研究。

  • 运行环境与依赖

    • Python 3.8+（仓库中使用 asyncio/uv 等特性）
    • uv（Astral 的 uv 库，用于启动与调度 MCP 服务）
    • Civ 6 及 FireTuner
    • 操作系统：macOS、Windows（需相应的 GUI 自动化支持）

  • 典型工作流

    • 启动 Civ6 与 FireTuner
    • 启动 Civ6 MCP 服务器
    • 使用 MCP 客户端（Claude/Codex/Gemini 等）连接并发起会话
    • 通过标准工具集读取状态，调用工具执行操作，结束回合，，并通过 diary/地图/空间追踪等扩展进行分析

服务器信息

访问项目