MCP Crossword Tools

🚀 Crossword MCP Server

This repository hosts a Crossword Support MCP Server. It can read text files containing the crossword grid and clue definitions, register candidate words, check consistency, and draw the final grid.

🚀 Quick Start

Required Environment

• Python 3.11 or later
• uv

Dependencies are installed via uv run, so there's no need to manually run pip install beforehand.

Data Format

• Grid (data/grid-*.txt)
  • Use full-width numbers to indicate row and column numbers.
  • Input available cells are represented by full-width ？.
  • Black cells are represented by full-width ＃.
• Clues (data/clue-*.txt)
  • JSON Lines with one record per line.
  • Specify all of id, direction ("across" / "down"), row, col, length, and clue.

The data/ folder contains sample pairs of grid and clue files. If you want to solve different crossword puzzles, refer to these files to create your own grid and clue files.

✨ Features

Provided Tools

The MCP server provides the following tools (methods):

Registration and Usage in Claude Code

To add this server to Claude Code, run the following command at the project root:

claude mcp add crossword_tools --scope project -- uv run --with fastmcp fastmcp run src/server.py

(crossword_tools is the MCP name assigned to this server. Change it as needed.)

After registration, in Claude Code, select the custom slash command /crossword_tools and specify the grid and clue files (or text) as arguments. Following the prompts, Claude Code will autonomously initialize the state, add candidate words, check consistency, and if a final solution is reached, draw the solution and generate a report.

/crossword_tools:solve_crossword (MCP) grid-001.txt clue-001.txt

📄 License

This repository is provided under the MIT License.