Wordle MCP (Python)

A MCP Server for fetching the Wordle solutions via the Wordle 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"
      ]
    }
  }
}

Related MCP server: MCP Metaculus Server

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.