ti4-mcp

MCP server for Twilight Imperium 4 — provides game data, rules lookup, faction strategy guides, and setup assistance through the Model Context Protocol.

Supported Content

• Base game (17 factions)
• Prophecy of Kings (7 factions)
• Codex I–IV (errata, updated components, Council Keleres)
• Thunder's Edge (5 factions, breakthroughs, galactic events)

Installation

npm install
npm run build

Requires Node.js 18+.

Usage

Claude Code

From GitHub:

claude mcp add ti4 -- npx --yes github:surewht/ti4-mcp

From a local clone:

claude mcp add ti4 node /path/to/ti4-mcp/dist/index.js

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ti4": {
      "command": "npx",
      "args": ["--yes", "github:surewht/ti4-mcp"]
    }
  }
}

Inspector

npm run inspect

Tools (27)

Game Context

Tool	Description
set_game_context	Set game session context (expansions, player count, factions, slices) — subsequent tools auto-apply it
get_game_context	View current game context
clear_game_context	Clear game context

Factions

Tool	Description
list_factions	List factions for active expansions
get_faction	Detailed faction info (abilities, starting tech, units, leaders, promissory note)
get_faction_guide	Strategy guide — strengths, weaknesses, tips, tech paths
list_faction_guides	List all available faction guides

Technologies

Tool	Description
get_tech	Look up a technology by ID
get_tech_path	Get recommended tech path for a faction

Objectives

Tool	Description
list_objectives	List objectives, filter by type (public/secret) and stage (1/2)
get_objective	Look up a specific objective

Agendas

Tool	Description
list_agendas	List agenda cards, filter by type (law/directive) or election type
get_agenda	Look up a specific agenda

Action Cards

Tool	Description
list_action_cards	List action cards, filter by play timing keyword
get_action_card	Look up a specific action card

Relics & Exploration

Tool	Description
list_relics	List all relics
get_relic	Look up a specific relic
list_explore_cards	List exploration cards, filter by trait

Planets & Systems

Tool	Description
list_planets	List planets, filter by trait or tech specialty
get_planet	Look up a specific planet
get_system	Look up a system tile by number (planets, wormholes, anomalies)

Strategy & Setup

Tool	Description
get_strategy_notes	Strategic analysis for a faction given the game state
setup_game	Generate a complete game setup (draft pool, strategy card order, etc.)
suggest_map	Suggest a balanced map layout for the player count
analyze_slices	Analyze map slices for balance (resources, influence, tech specialties)

Rules & Search

Tool	Description
get_rules	Look up rules by keyword
search	Full-text search across all game data categories

Game Context

Set your game setup once, and all tools auto-apply it:

"Set game context: 6 players, base + PoK + Codex 3"

The AI calls set_game_context with your expansions and player count. After that, tools like list_factions, list_objectives, suggest_map, etc. automatically use those expansions without you specifying them each time.

You can still override expansions per-call if needed.

Data

All game data lives in data/ as JSON files:

File	Content
factions.json	30 factions with abilities, starting tech, units, leaders
technologies.json	All technologies across expansions
objectives.json	Public stage I/II and secret objectives
agendas.json	Law and directive agenda cards
action-cards.json	Action cards with play timing
strategy-cards.json	Strategy cards with primary/secondary abilities
systems.json	System tiles with planets, wormholes, anomalies
planets.json	Individual planet data
units.json	Unit stats (cost, combat, move, capacity, abilities)
promissory-notes.json	Faction and generic promissory notes
relics.json	Relics (PoK)
explores.json	Exploration cards (PoK)
leaders.json	Agents, commanders, heroes
breakthroughs.json	Breakthroughs (Thunder's Edge)
galactic-events.json	Galactic events (Thunder's Edge)
rules.json	Rules reference with subsections
tile-tiers.json	Tile quality tiers for map balancing
factions/*.guide.json	30 faction strategy guides from competitive community sources

Expansions

Tools accept an expansions parameter to control which content is included:

• base — Base game
• pok — Prophecy of Kings
• codex-1 through codex-4 — Codex volumes (includes omega replacements)
• thunders-edge — Thunder's Edge expansion

When expansions include codex volumes, updated components automatically replace their older base/PoK versions.

License

MIT