GitHub Projects V2

Gerencie o GitHub Projects V2 usando a API GraphQL do GitHub.

Documentação

GitHub Projects V2 MCP Server

Um servidor Model Context Protocol (MCP) que fornece ferramentas para gerenciar GitHub Projects V2 através do Claude e outros clientes MCP. Este servidor usa a API GraphQL do GitHub para interagir com GitHub Projects V2.

Recursos

Listar e visualizar GitHub Projects V2 para usuários e organizações
Obter campos e itens do projeto (issues, PRs, issues de rascunho)
Criar issues e adicioná-las a projetos
Criar issues de rascunho diretamente em projetos
Atualizar valores de campos de itens do projeto
Excluir itens de projetos

Uso

Este servidor pode ser usado com qualquer cliente MCP, como o Claude Desktop. Adicione-o à configuração do seu cliente MCP (ex.: claude_desktop_config.json).

Opção 1: Usando o Pacote Publicado

Aqui está um exemplo de configuração usando uvx como executor de comandos:

{
  "mcpServers": {
    "github-projects": {
      "command": "uvx",
      "args": [
        "mcp-github-projects"
      ],
      "env": {
        "GITHUB_TOKEN": "your_pat_here"
      }
    }
  }
}

Certifique-se de substituir your_pat_here pelo seu token de acesso pessoal do GitHub real.

Opção 2: A partir do Código-Fonte

Para executar o projeto diretamente a partir do código-fonte, siga estes passos:

Configuração

Clone o repositório:

git clone git@github.com:Arclio/github-projects-mcp.git
cd github-projects-mcp

Crie e ative um ambiente virtual:
```
uv venv
source venv/bin/activate
```
Instale as dependências:
```
uv pip install -e .
```
Defina seu token do GitHub como uma variável de ambiente:

Crie um token de acesso pessoal do GitHub e conceda a ele as permissões necessárias. As permissões necessárias são: repo, project e read:org.

Adicione o token ao seu arquivo .env após executar este comando:
```
cp .env.example .env
```
Em seguida, adicione o seguinte ao seu arquivo .env:
```
export GITHUB_TOKEN=your_personal_access_token
```

Uso a partir do código-fonte

Ao usar a partir do código-fonte, configure seu cliente MCP da seguinte forma:

{
  "mcpServers": {
    "github-projects": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/github-projects-mcp",
        "run",
        "mcp-github-projects"
      ],
      "env": {
        "GITHUB_TOKEN": "your_pat_here"
      }
    }
  }
}

Certifique-se de substituir /path/to/github-projects-mcp e your_pat_here pelo caminho real do seu repositório e pelo token de acesso pessoal do GitHub.

Ferramentas Disponíveis

list_projects: Listar GitHub Projects V2 para uma organização ou usuário
get_project_fields: Obter campos disponíveis em um GitHub Project V2
get_project_items: Obter itens em um GitHub Project V2 (suporta filtragem por estado ou campos personalizados de seleção única)
create_issue: Criar uma nova issue no GitHub
add_issue_to_project: Adicionar uma issue existente do GitHub a um Project V2
update_project_item_field: Atualizar o valor de um campo para um item do projeto
create_draft_issue: Criar uma issue de rascunho diretamente em um GitHub Project V2
delete_project_item: Excluir um item de um GitHub Project V2

Consulte a documentação das ferramentas no código do servidor para obter informações detalhadas de uso.

Desenvolvimento

O projeto está estruturado da seguinte forma:

src/github_projects_mcp/: Diretório principal do pacote
- server.py: Implementação do servidor MCP com definições de ferramentas
- github_client.py: Cliente GraphQL para interações com a API do GitHub

Para contribuir, certifique-se de:

Adicionar tratamento de erros adequado para todas as operações GraphQL
Adicionar anotações de tipo para todas as funções e parâmetros
Atualizar a documentação ao adicionar novas ferramentas ou recursos