Chess UCI

Conecte-se a motores de xadrez compatíveis com UCI, como o Stockfish, para jogar e analisar partidas. Requer um binário local do motor de xadrez.

GitHub
2
Experimente este MCPPatrocinado

Documentação

chess-uci-mcp

Uma ponte MCP que fornece uma interface para mecanismos de xadrez compatíveis com UCI (como Stockfish ou Leela Chess Zero).

O lado UCI roda em esca: ele fala o protocolo com o mecanismo e responde a todas as perguntas de xadrez que a ponte tiver ao longo do caminho.

Dependências

Você precisa ter Python 3.12 ou mais recente, e também uv/uvx instalados.

Uso

Para funcionar, é necessário um mecanismo de xadrez compatível com UCI instalado, como o Stockfish (testado com Stockfish 17).

No caso do Stockfish, você pode baixá-lo em https://stockfishchess.org/download/.

No macOS, você pode usar brew install stockfish.

Você precisa descobrir o caminho para o binário do mecanismo compatível com UCI; para exemplos de configuração adicionais, o caminho é, por exemplo, /usr/local/bin/stockfish (que é o padrão para o Stockfish instalado no macOS usando Brew).

A configuração adicional deve ser feita na sua configuração do MCP; para o Claude Desktop, este é o arquivo claude_desktop_config.json (encontre-o no menu Configurações, em Desenvolvedor, e depois Editar Configuração).

O caminho completo em diferentes sistemas operacionais:

  • macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Adicione as seguintes configurações à sua configuração do MCP (dependendo da forma como você prefere executá-lo):

Uvx (recomendado)

O Uvx é capaz de executar diretamente o aplicativo Python pelo nome, garantindo todas as dependências, em um ambiente virtual criado automaticamente. Esta é a forma preferida de executar a ponte chess-uci-mcp.

Configure o arquivo de configuração do seu servidor MCP (por exemplo, a configuração do Claude Desktop) da seguinte forma:

"mcpServers": {
  "chess-uci-mcp": {
    "command": "uvx",
    "args": ["chess-uci-mcp@latest", "/usr/local/bin/stockfish"]
  }
}

Para passar opções ao mecanismo, adicione-as ao array args. Por exemplo, para definir as opções Threads e Hash para o Stockfish:

"mcpServers": {
  "chess-uci-mcp": {
    "command": "uvx",
    "args": [
      "chess-uci-mcp@latest", 
      "/usr/local/bin/stockfish",
      "-o", "Threads", "4",
      "-o", "Hash", "128"
    ]
  }
}

Uv

Use-o se você tiver o repositório clonado localmente e executar a partir dele:

"mcpServers": {
  "chess-uci-mcp": {
    "command": "uv",
    "args": ["run", "chess-uci-mcp", "/usr/local/bin/stockfish"]
  }
}

Da mesma forma, para passar opções ao executar com uv:

"mcpServers": {
  "chess-uci-mcp": {
    "command": "uv",
    "args": [
      "run", 
      "chess-uci-mcp", 
      "/usr/local/bin/stockfish",
      "-o", "Threads", "4",
      "-o", "Hash", "128"
    ]
  }
}

Opções de Linha de Comando

O aplicativo aceita as seguintes opções de linha de comando:

  • ENGINE_PATH: (Obrigatório) O caminho para o executável do mecanismo de xadrez compatível com UCI.
  • --uci-option ou -o: Define uma opção UCI. Esta opção pode ser usada várias vezes. Ela recebe dois argumentos: o nome da opção e seu valor (por exemplo, -o Threads 4).
  • --think-time: O tempo de pensamento padrão para o mecanismo em milissegundos. O padrão é 1000.
  • --debug: Ativa o registro de depuração.

Comandos MCP Disponíveis

A ponte fornece os seguintes comandos MCP:

  1. analyze - Analisar uma posição de xadrez especificada pela string FEN
  2. get_best_move - Obter o melhor movimento para uma posição de xadrez
  3. set_position - Definir a posição atual de xadrez
  4. engine_info - Obter informações sobre o mecanismo de xadrez
  5. get_engine_options - Obter todas as opções UCI disponíveis do mecanismo com seus metadados e valores atuais
  6. set_engine_options - Definir uma ou mais opções UCI do mecanismo em tempo de execução

Desenvolvimento

# Clone the repository
git clone https://github.com/AnglerfishChess/chess-uci-mcp.git
# ... or
#    git clone git@github.com:AnglerfishChess/chess-uci-mcp.git

cd chess-uci-mcp

# Create a virtual environment
uv venv --python python3.13

# Activate the virtual environment
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate     # On Windows

# Install the package in development mode
#    uv pip install -e .
# or, with development dependencies
uv pip install -e ".[dev]"

# Resync the packages:
uv sync --extra=dev

# Run tests
pytest

# Check code style
ruff check

Processo de lançamento

A lista de verificação está na habilidade releasing sob .claude/skills/, para que um lançamento ocorra sempre da mesma forma: pré-condições, aumento de versão, tag, lançamento no GitHub. Publicar um lançamento no GitHub é o gatilho — a partir daí, .github/workflows/publish.yml compila o pacote e o envia para o PyPI através de um editor confiável, e depois republica a entrada do registro MCP. Ambos autenticam via OIDC, então nenhum token é armazenado neste repositório ou na máquina de qualquer desenvolvedor.

Nada é automático: um lançamento só acontece quando uma pessoa publica o lançamento no GitHub.

pyproject.toml contém a versão, e todas as outras cópias são derivadas dela:

uv sync --extra=dev    # updates uv.lock, keeping the dev tools installed
uv run python .claude/skills/releasing/scripts/sync_version.py

Isso grava chess_uci_mcp/__init__.py e ambos os campos de versão em server.json. Passar --check em vez disso relata divergências sem tocar em nada, que é o que o CI executa.

O registro MCP

registry.modelcontextprotocol.io é o índice autoritativo de servidores MCP públicos, consumido por Smithery, PulseMCP, Docker Hub e outros. Ele não tem caixa de busca; é uma API:

curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=chess-uci-mcp&limit=3"

A listagem é descrita por server.json, sob o nome io.github.AnglerfishChess/chess-uci-mcp. A autenticação do GitHub concede o namespace io.github.<user>/*; um namespace de organização adicionalmente exige direitos de Proprietário nessa organização, e o nome diferencia maiúsculas de minúsculas.

A propriedade do pacote PyPI é comprovada pelo marcador mcp-name: perto do topo deste README, que se torna a descrição do pacote no PyPI. O registro o lê do artefato publicado, então adicioná-lo ao git não é suficiente — ele só conta quando um lançamento que o contém chega ao PyPI. Observe também que o registro limita description a 100 caracteres, onde o PyPI não limita, e é por isso que server.json carrega sua própria descrição de uma linha em vez de reutilizar a do projeto.

Projetos relacionados

  • esca — a biblioteca de xadrez MIT em Rust/Python que fala UCI para este servidor.
  • chessplaza — trapaceiros de xadrez de IA com personalidades, jogando através deste servidor.

Sites relacionados

Certificado pelo MCP Review