Wordle MCP (Python)

> [!NOTE]

> To check out the Go version of this MCP Server (lighter, faster), click here

A MCP Server for fetching the Wordle solutions via the Wordle API.

> [!IMPORTANT]

> Wordle solutions are only available from 2021-05-19, to 23 days in the future.

> Any other attempts at calling other dates will return an error from the API

Index

• Get Started
  • Using Docker (recommended)
  • Installing via `uvx`
• Examples on Claude Desktop
• Development
  • Releasing
• Contributing

Get Started

Using Docker (recommended)

Ensure that you have Docker installed.

Add this to your MCP Server configuration:

{
  "mcpServers": {
    "Wordle MCP (Python)": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--init",
        "-e",
        "DOCKER_CONTAINER=true",
        "ghcr.io/cr2007/mcp-wordle-python:latest"
      ]
    }
  }
}

> [!IMPORTANT]

> If you get an error on Claude Desktop for the first time, just make sure to pull the image before running.

> `docker pull ghcr.io/cr2007/mcp-wordle-python:latest`

Installing via `uvx`

The quickest and easiest method to get started. Make sure to install `uv` before adding this in your configuration.

Add this to your MCP server configuration:

{
  "mcpServers": {
    "Wordle MCP (Python)":{
      "command": "uvx",
        "args": [
          "--from",
          "git+https://github.com/cr2007/mcp-wordle-python",
          "mcp-wordle"
        ]
      }
  }
}

Examples on Claude Desktop

Development

See CONTRIBUTING.md for setting up a dev environment and running the test suite. Every push and pull request is validated by the CI workflow.

Releasing

Releases are cut by pushing a `vMAJOR.MINOR.PATCH` tag:

1. Bump `version` in `pyproject.toml` to match the new release.

2. Commit that change.

3. Tag the commit, e.g. `git tag v1.2.3` and `git push origin v1.2.3`.

The publish workflow rejects the release if the tag doesn't match `pyproject.toml`'s version, or if the test/`uvx`/Docker checks fail. On success, it pushes `ghcr.io/cr2007/mcp-wordle-python` tagged with the full version, `major.minor`, `major`, and `latest`.

Contributing

Contributions are welcome! You may fork the repo, create your changes in a branch, and then create a Pull Request

See CONTRIBUTING.md for a full guide on setting up a dev environment, running tests, and commit/PR conventions.