<!-- omit from toc -->
# Wordle MCP (Python)

[![CI](https://github.com/cr2007/mcp-wordle-python/actions/workflows/ci.yml/badge.svg)](https://github.com/cr2007/mcp-wordle-python/actions/workflows/ci.yml)
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/cr2007/mcp-wordle-python)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/cr2007/mcp-wordle-python)

> [!NOTE]
> To check out the Go version of this MCP Server (lighter, faster), [click here](https://github.com/cr2007/mcp-wordle-go)


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.<br>
> Any other attempts at calling other dates will return an error from the API

<!-- omit from toc -->
# Index
- [Get Started](#get-started)
  - [Using Docker (recommended)](#using-docker-recommended)
  - [Installing via `uvx`](#installing-via-uvx)
- [Examples on Claude Desktop](#examples-on-claude-desktop)
- [Development](#development)
  - [Releasing](#releasing)
- [Contributing](#contributing)

---

# Get Started

## Using Docker (recommended)

Ensure that you have [Docker](https://www.docker.com) installed.<br>
Add this to your MCP Server configuration:

```json
{
  "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.<br>
> `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`](https://docs.astral.sh/uv) before adding this in your configuration.<br>
Add this to your MCP server configuration:

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

# Examples on Claude Desktop

<div align="center">
    <img width=75%, src="./images/Claude_Chat-Example.png">
</div>

# Development

See [CONTRIBUTING.md](./CONTRIBUTING.md) for setting up a dev environment and running the test suite. Every push and pull request is validated by the [CI workflow](./.github/workflows/ci.yml).

## 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](./.github/workflows/publish-image.yml) 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](https://github.com/cr2007/mcp-wordle-python/fork) the repo, create your changes in a branch, and then create a [Pull Request](https://github.com/cr2007/mcp-wordle-python/compare)

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