wordlebot

An MCP server that helps solve Wordle. You tell it which letters were hits, misses, or in the wrong spot; it returns five-letter words consistent with every clue, best guesses first.

What it does

• suggest_words — give it your guess history (each word + the tile colors) and it returns every accepted word still consistent with the clues, ranked by a letter-frequency heuristic.
• starting_words — strong opening guesses.
• validate_word — is a word accepted by Wordle?
• wordle://wordlist/metadata (resource) — provenance of the bundled word list.

The word list (data source & honesty caveat)

The bundled list is 14,855 five-letter words: the set of accepted guesses, sourced from the public tabatkins/wordle-list repository, which extracts them straight from Wordle's own source code. It's normalized (lowercased, de-duplicated, sorted, every entry validated as exactly five ASCII letters) and shipped as a static file with a SHA-256 checksum and retrieval date in src/wordle_mcp/data/words.meta.json.

Caveat, stated plainly: since the NYT acquisition, the daily-answer subset has drifted — words are played out of original order, some have repeated, and some new answers were never on the original list. So no static list perfectly mirrors NYT's live answer set. For a constraint solver this is fine: we filter accepted words against your clues. But the ranking is a heuristic for a strong guess, not a probability of being today's answer.

To refresh the list from source at any time:

python scripts/refresh_wordlist.py

Install

Requires Python 3.10+.

git clone https://github.com/skeeved/wordlebot && cd wordlebot
python -m venv .venv && source .venv/bin/activate
pip install -e .

(Or, with uv: uv sync.)

Connect it to Claude Desktop

The server is a local stdio MCP server, so Claude Desktop can launch it directly. The simplest setup is to install the package into a virtual environment and point Claude at the generated console script.

1. Install the package

From the repository root:

python -m venv .venv
source .venv/bin/activate
pip install -e .

2. Add the server to Claude Desktop

Open Claude Desktop Settings → Developer → Edit Config and add or update ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) with an absolute path:

{
  "mcpServers": {
    "wordlebot": {
      "command": "/<path>/wordlebot/.venv/bin/wordlebot"
    }
  }
}

If you prefer not to activate the virtual environment, run it through uv instead:

{
  "mcpServers": {
    "wordlebot": {
      "command": "uv",
      "args": ["--directory", "/<path>/wordlebot", "run", "wordlebot"]
    }
  }
}

Then fully quit and relaunch Claude Desktop. If the connection is successful, Claude should show an MCP server indicator and expose the server's tools.

3. Test it interactively

To try the server outside of a host app, use the MCP Inspector:

npx @modelcontextprotocol/inspector wordlebot

Connect it to VS Code

VS Code can also use this server through its MCP configuration file. The easiest approach is to create or edit .vscode/mcp.json in your workspace (or use the Command Palette command MCP: Open User Configuration).

Example workspace configuration:

{
  "servers": {
    "wordlebot": {
      "type": "stdio",
      "command": "/<path>/wordlebot/.venv/bin/wordlebot"
    }
  }
}

Or, if you want VS Code to launch it through uv:

{
  "servers": {
    "wordle-solver": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/<path>/wordlebot/.venv/bin", "run", "wordlebot"]
    }
  }
}

After saving the file, VS Code will usually prompt you to trust and start the server. Once it is running, the tools should appear in chat and agent workflows.

How to describe feedback

Each guess is a word plus a 5-character pattern, left to right:

Symbol	Meaning
G	green — correct letter, correct spot
Y	yellow — letter is in the word, wrong spot
B	gray/black — letter not in the word

(2/1/0 and . x _ are also accepted as G/Y/B.)

Example call to suggest_words:

{
  "guesses": [
    { "word": "crane", "feedback": "BGGGB" },
    { "word": "trail", "feedback": "BGGBB" }
  ],
  "max_results": 10
}

→ returns { "total_matches": 18, "words": ["grans", "brank", ... , "prank", ...], ... }

In practice you just talk to your MCP host: "I played CRANE and got gray-green-green-green-gray, then TRAIL and got gray-green-green-gray-gray. What should I try?" — the host fills in the tool call.

The one subtle rule: duplicate letters

A gray tile does not always mean "letter absent." If you guess a word with two of a letter but the answer has only one, one copy comes back colored and the other gray — the gray means "no more copies," not "none at all."

Analogy: requesting two ocean-view rooms at a hotel with only one. The desk confirms one and declines the other; the decline doesn't mean zero ocean-view rooms exist — just none beyond the one you got.

The solver implements this exactly: green + yellow tiles set a minimum count for a letter; any gray tile for that same letter turns the minimum into an exact count. This is verified by a property test (tests/test_solver.py::test_matches_equals_reference) that checks the matcher against a from-scratch implementation of Wordle's real feedback rule across hundreds of thousands of answer/guess/candidate combinations.

Development

pip install -e ".[dev]"
pytest -q

Notes on the MCP SDK

Built on the v1.x MCP Python SDK (mcp[cli], FastMCP), which is the stable, production-recommended line. It is pinned >=1.27,<2: SDK v2 (targeting the 2026-07-28 spec) renames FastMCP to MCPServer and moves to a stateless request/response protocol. When you migrate, the tool functions here carry over unchanged; only the server bootstrap in src/wordle_mcp/server.py needs updating per the SDK migration guide.

License

GPL-3.0-only.