smt-sudoku-mcp
This server provides an MCP-based Sudoku toolkit powered by SMT/Z3 for generating, validating, and solving puzzles.
Generate a uniquely-solvable Sudoku puzzle at a chosen difficulty (very easy to very hard), returning the grid and actual clue count.
Validate a partially-filled grid, reporting conflicts, empty cells, and whether it can still be completed.
Validate a fully-filled grid to check whether it is a correct Sudoku solution.
Solve an unsolved grid, returning a solution or reporting conflicting givens / unsatisfiable cases.
Works as an MCP server over stdio or streamable-http, with stateless tool calls and 1-indexed cell positions for results.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@smt-sudoku-mcp Generate a hard Sudoku puzzle"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
smt-sudoku-mcp
Now, your agents can play Sudoku confidently!
An MCP server that demonstrates the power of satisfiability modulo theories (SMT) solving, using Z3, through the classic constraint-satisfaction puzzle of Sudoku.
Sudoku maps cleanly onto SMT primitives: generating a puzzle means finding a model that satisfies the Sudoku constraints and then proving a reduced set of clues still has only one solution; validating a grid means checking those same constraints against given cell values; solving a puzzle means finding a model or proving none exists.
As of 1.0.0, the four tools' input/output schemas below are a stable public contract: any breaking change to them will be called out explicitly in CHANGELOG.md and reflected in a major version bump.
Tools
All four tools are stateless: every call takes and/or returns a complete grid explicitly, with no server-side session state.
A Sudoku grid is represented as {"rows": [[...9 ints...], ...9 rows...]}, where each cell is 1-9 for a given digit or 0 for an empty cell. Any tool result that names a specific cell (a conflict) reports row/col as 1-indexed, matching how Sudoku cells are conventionally described in text (row 1, column 1 is the top-left cell).
generate_sudoku_puzzle
Generates a new, uniquely-solvable Sudoku puzzle.
Input:
difficulty— one of"very easy","easy","medium","hard", or"very hard"(default"medium"), mapping to an approximate target clue count:63,51,42,30, and21respectively."very hard"'s target of21sits just above the proven minimum of 17 givens for any uniquely-solvable Sudoku puzzle, so in practice it commonly lands noticeably above 21 (e.g. mid-20s), since removal stops once no further cell can be cleared without breaking uniqueness.Output:
{"puzzle": <grid>, "difficulty": <str>, "givens": <int>}—givensis the actual number of filled cells, which may be slightly above the target if removing further cells would have broken uniqueness.
validate_partial_sudoku_solution
Checks whether a partially-filled grid is conflict-free and, if so, whether it can still be completed.
Input:
grid— a partial grid (0 for empty cells).Output:
{"conflicts": [<cell>, ...], "is_completable": <bool | null>, "empty_cells": [<cell>, ...], "has_conflicts": <bool>, "empty_cells_count": <int>}—is_completableisnullwhen conflicts are present, since completability is not a meaningful question until they are resolved.empty_cellslists every still-empty cell regardless ofhas_conflicts;empty_cells_countislen(empty_cells).
validate_full_sudoku_solution
Checks whether a fully-filled grid is a correct Sudoku solution.
Input:
grid— expected to have no empty cells.Output:
{"has_empty_cells": <bool>, "conflicts": [<cell>, ...], "is_valid": <bool>}.
solve_sudoku_puzzle
Solves an unsolved grid, or reports why it cannot be solved.
Input:
grid— a partial grid to solve (0 for empty cells).Output:
{"status": "satisfiable" | "conflicting_givens" | "unsatisfiable", "solution": <grid | null>, "conflicts": [<cell>, ...]}.conflictsis only populated whenstatusis"conflicting_givens"(two given cells directly violate a row/column/box rule);"unsatisfiable"means the givens are pairwise conflict-free but no completion exists.
Related MCP server: MCP Solver
Installation
Requires Python 3.13+. The package is published on PyPI.
The simplest way to run it is with uvx, which fetches the package into an ephemeral environment on first use and requires no separate install step:
uvx smt-sudoku-mcpAlternatively, install it with pip (or uv pip) and run the installed console script directly:
pip install smt-sudoku-mcp
smt-sudoku-mcpTo work on the source itself rather than the published package, see Development below.
Using it with an MCP client
This server speaks MCP over stdio by default, so any MCP client that can launch a subprocess can use it without further setup. Set SMT_SUDOKU_MCP_TRANSPORT=streamable-http instead if the client needs to reach a standalone HTTP service; see Configuration.
Claude Code
claude mcp add smt-sudoku -- uvx smt-sudoku-mcpClaude Desktop
Add an entry under Settings → Developer → Edit Config (claude_desktop_config.json):
{
"mcpServers": {
"smt-sudoku": {
"command": "uvx",
"args": ["smt-sudoku-mcp"]
}
}
}Other MCP clients and agent frameworks
Any client that accepts a raw MCP server definition — Cursor, Windsurf, VS Code, or a custom agent built on an MCP SDK — can use the same command/args pair: uvx and ["smt-sudoku-mcp"]. For streamable-http, run the server separately with SMT_SUDOKU_MCP_TRANSPORT=streamable-http uvx smt-sudoku-mcp and point the client at http://<host>:<port>/mcp rather than giving it a command to launch.
Once connected, an agent can call the four tools above as it would any other tool. For example, asking an agent to "generate a hard Sudoku puzzle, then solve it and check the solution" will chain generate_sudoku_puzzle, solve_sudoku_puzzle, and validate_full_sudoku_solution without further guidance, since each tool's description and schema are sufficient for the agent to plan the sequence itself.
Configuration
Environment variables, all optional:
Variable | Default | Description |
|
|
|
|
| Bind host, |
|
| Bind port, |
| (none) | Comma-separated browser origins to trust, |
The server has no built-in authentication or authorization of its own: SMT_SUDOKU_MCP_ALLOWED_ORIGINS and the request guard it feeds protect against spoofed browser origins and DNS-rebinding-style attacks, not against an arbitrary network client calling its tools. There is no scope for adding authentication — this server is intended to be run on a local machine or an otherwise trusted network, never exposed directly to an untrusted network.
Development
To run the server from a source checkout instead of the published package, use uv:
uv sync
uv run smt-sudoku-mcpSee AGENTS.md for architecture notes and the full set of development commands (just -l).
Contributing
Issues and pull requests are welcome; see CONTRIBUTING.md. See CONTRIBUTORS.md for the list of contributors, and CHANGELOG.md for the release history.
Security
See SECURITY.md for the vulnerability disclosure policy.
License
MIT.
Available Tools
4 toolsgenerate_sudoku_puzzleGenerate Sudoku PuzzleA
Generate a new, uniquely-solvable Sudoku puzzle at the given difficulty.
Inputs: difficulty. Returns: Result of generating a new puzzle.
solve_sudoku_puzzleSolve Sudoku PuzzleA
Solve an unsolved Sudoku grid, or report why it cannot be solved.
Inputs: grid (required). Returns: Result of solving an unsolved grid.
validate_full_sudoku_solutionValidate Full Sudoku SolutionA
Check whether a fully-filled Sudoku grid is a correct solution.
Inputs: grid (required). Returns: Result of validating a fully-filled grid.
validate_partial_sudoku_solutionValidate Partial Sudoku SolutionA
Check whether a partially-filled Sudoku grid is conflict-free and still completable.
Inputs: grid (required). Returns: Result of validating a partially-filled grid.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clear, non-overlapping purpose: generating puzzles, validating partial solutions, validating complete solutions, and solving puzzles. There is no ambiguity about which tool to use for a given task.
All tool names follow a consistent verb_noun snake_case pattern. The two validation tools share the same verb and differ only by the qualifier 'partial' or 'full', which is intuitive and predictable.
Four tools is a well-scoped set for a Sudoku-specific server. Each tool addresses a distinct core operation without unnecessary bloat or redundancy.
The tool surface covers the full Sudoku workflow: puzzle generation, solving, and validation of both in-progress and completed grids. No significant missing operations exist for the stated domain.
Maintenance
Related MCP Connectors
Number puzzle API + MCP: solver-checked puzzles as JSON/SVG, daily puzzle. $5/mo; 50 free/day.
Deterministic Sudoku puzzles, progress checks, logical hints, and step-by-step solutions.
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables solving Constraint Satisfaction Problems (CSP) like N-Queens, graph coloring, and Sudoku, as well as Linear Programming optimization problems through both MCP tools and HTTP API endpoints.2MIT
- AlicenseNot gradedqualityNot gradedmaintenanceAn MCP server that enables Large Language Models to interactively create, edit, and solve constraint models using backends like MiniZinc, Z3, PySAT, and Clingo. It bridges natural language with symbolic reasoning for solving complex logical, SAT, SMT, and optimization problems.MIT
- FlicenseAqualityDmaintenanceEnables solving constraint satisfaction problems, mathematical equations, and logic puzzles using the Z3 SMT solver through natural language.13-
- AlicenseNot gradedqualityCmaintenanceMCP server for puzzle generation: word search generator, crossword generator, and sudoku generator + solver, with printable PDF worksheets, themed word banks, and verifiable LLM evals. Works with Claude Desktop, Cursor, Windsurf, and any Model Context Protocol client. From the makers of puzzletide.com.105 npmMIT