junyeong-nero/gomoku-mcp-server

Gomoku MCP Server

A Gomoku (Five-in-a-Row) game server that enables LLMs to play through the Model Context Protocol (MCP). Features intelligent threat analysis and strategic move suggestions.

Features

• 15x15 Standard Board: Classic Gomoku gameplay
• MCP Tool Integration: Full game control through MCP tools
• Threat Analysis: Detects open-fours, closed-fours, open-threes, and gap patterns
• Move Suggestions: Priority-ranked move recommendations based on tactical analysis
• Multi-Model Support: Works with any LLM via OpenRouter (Gemini, Grok, Kimi, etc.)
• CLI and GUI: Both command-line and graphical interfaces
• Two Player Mode: Watch two LLMs compete against each other

Architecture

src/
├── game/
│   ├── gomoku.py      # Core game logic
│   └── patterns.py    # Pattern detection engine
├── mcp_server/
│   └── server.py      # FastMCP server with game tools
├── prompts/
│   ├── system_prompt.py   # AI player system prompt
│   └── user_prompt.py     # Turn prompt template
├── agents.py          # LLM Agent for tool interactions
├── manager.py         # Game state coordinator
├── cli.py             # Command-line interface
└── gui.py             # Graphical interface

Installation

Environment Setup with uv

uv sync
uv pip install -e .

OpenRouter API Key

export OPENROUTER_API_KEY="YOUR_API_KEY"

Run

uv run src/cli.py   # Command-line interface (PvE or AI vs AI)
uv run src/gui.py   # Graphical interface (PvE or AI vs AI)

Two Player Mode (LLM vs LLM)

두 개의 LLM이 서로 오목을 두는 대결을 관전할 수 있습니다.

CLI에서:

uv run src/cli.py
# Select "2. Two Player 모드 (AI vs AI)"

GUI에서:

uv run src/gui.py
# Open http://localhost:8000
# Select "⚔️ AI vs AI" mode
# Choose models for Black and White
# Click "게임 시작"

How It Works

1. The MCP server exposes game tools: set_stone, analyze_threats, get_suggested_moves, etc.
2. The LLM agent receives the current game state and turn prompt
3. The agent analyzes threats using analyze_threats() and gets ranked moves via get_suggested_moves()
4. Based on priority (blocking opponent fours > creating own threats > strategic positioning), the agent places a stone
5. The pattern detector evaluates: Open-4, Closed-4, Open-3, Closed-3, Gap patterns

Threat Priority Levels

Sample Games

• gemini-2.5-flash

• grok4-fast

• kimi-k2-thinking

MCP Configuration

Add to your MCP client configuration:

{
  "mcp-gomoku": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/gomoku-mcp-server/",
      "run",
      "src/server.py"
    ]
  }
}

Available MCP Tools