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.