Google Sheets Kanban MCP Server

MCP Server - Google Sheets Kanban

Servidor MCP (Model Context Protocol) para gerenciamento de tarefas em um quadro Kanban utilizando Google Sheets como backend.

Características

• Integração com Google Sheets: Usa Google Sheets API v4 para armazenamento de dados
• Modelos Pydantic: Validação de dados com Pydantic v2
• Operações em Lote: Suporte para adicionar e atualizar múltiplas tarefas de uma vez
• Busca Avançada: Filtros por prioridade, status, contexto, projeto e texto
• Paginação: Suporte completo para navegação paginada de resultados
• Protocolo MCP: Compatível com clientes MCP via STDIO

Configuração

Claude

Executar o seguinte comando na pasta do projeto:

claude mcp add --transport stdio kanban-sheets -- uv run -- --directory "caminho\projeto\sua\maquina" python main.py

Ferramentas Disponíveis

1. `get_one_task` - Buscar Tarefa Específica

Busca uma tarefa específica pelo ID da tarefa e nome do projeto.

Parâmetros:

• project (obrigatório): Nome do projeto
• task_id (obrigatório): ID único da tarefa

Exemplo:

{
  "project": "MCP Server Sheets",
  "task_id": "TASK-001"
}

Retorno (sucesso):

{
  "Projeto": "MCP Server Sheets",
  "Task ID": "TASK-001",
  "Task ID Root": "TASK-001",
  "Sprint": "Sprint 1",
  "Contexto": "Backend",
  "Descrição": "Implementar busca avançada",
  "Detalhado": "Adicionar filtros por prioridade, status e contexto",
  "Prioridade": "Alta",
  "Status": "Em Desenvolvimento",
  "Data Criação": "2025-10-24 10:30:00",
  "Data Solução": ""
}

Retorno (não encontrada):

{
  "error": "Tarefa 'TASK-999' não encontrada no projeto 'MCP Server'"
}

2. `list_tasks` - Listar e Buscar Tarefas

Lista e busca tarefas da planilha com filtros avançados e paginação opcional.

Parâmetros:

• filters (opcional): Objeto com critérios de busca
  • prioridade: Lista de prioridades (Baixa, Normal, Alta, Urgente)
  • status: Lista de status para filtrar
  • contexto: Filtro por contexto (busca parcial, case-insensitive)
  • projeto: Filtro por projeto (busca parcial, case-insensitive)
  • texto_busca: Busca em Descrição e Detalhado (case-insensitive)
  • task_id: Busca por Task ID específico
  • sprint: Filtro por Sprint
• pagination (opcional): Objeto com page (número da página) e page_size (itens por página)

Exemplos:

// 1. Listar todas as tarefas (comportamento legado)
{}

// 2. Com paginação
{
  "pagination": {
    "page": 1,
    "page_size": 20
  }
}

// 3. Buscar tarefas de alta prioridade
{
  "filters": {
    "prioridade": ["Alta", "Urgente"]
  }
}

// 4. Buscar tarefas em desenvolvimento com paginação
{
  "filters": {
    "status": ["Em Desenvolvimento"]
  },
  "pagination": {
    "page": 1,
    "page_size": 10
  }
}

// 5. Buscar por texto na descrição
{
  "filters": {
    "texto_busca": "implementar API"
  }
}

// 6. Combinar múltiplos filtros
{
  "filters": {
    "prioridade": ["Alta"],
    "status": ["Todo", "Em Desenvolvimento"],
    "contexto": "Backend",
    "projeto": "MCP Server"
  },
  "pagination": {
    "page": 1,
    "page_size": 25
  }
}

Retorno (sem paginação):

[
  {
    "Task ID": "TASK-001",
    "Contexto": "Backend",
    "Descrição": "...",
    ...
  },
  ...
]

Retorno (com paginação):

{
  "tasks": [...],
  "total_count": 45,
  "page": 1,
  "page_size": 25,
  "total_pages": 2,
  "has_next": true,
  "has_previous": false
}

3. `add_task` - Adicionar Tarefa

Adiciona uma nova tarefa na planilha.

Parâmetros:

• task: Objeto Task com todos os campos

Exemplo:

{
  "task": {
    "project": "MCP Server Sheets",
    "task_id": "TASK-001",
    "contexto": "Backend",
    "descricao": "Implementar busca avançada",
    "prioridade": "Alta",
    "status": "Todo",
    "task_id_root": "",
    "sprint": "Sprint 1",
    "detalhado": "Adicionar filtros por prioridade, status e contexto",
    "data_criacao": "2025-10-24",
    "data_solucao": ""
  }
}

4. `update_task` - Atualizar Tarefa

Atualiza uma tarefa existente pelo Task ID.

Parâmetros:

• task_id: ID da tarefa a ser atualizada
• updates: Dicionário com campos a atualizar

Exemplo:

{
  "task_id": "TASK-001",
  "updates": {
    "Status": "Concluído",
    "Data Solução": "2025-10-24"
  }
}

5. `batch_add_tasks` - Adicionar Múltiplas Tarefas

Adiciona múltiplas tarefas em uma única operação.

Parâmetros:

• batch: Objeto BatchTaskAdd contendo lista de tarefas

Exemplo:

{
  "batch": {
    "tasks": [
      {
        "project": "MCP Server",
        "task_id": "TASK-001",
        "contexto": "Backend",
        "descricao": "Tarefa 1",
        "prioridade": "Alta",
        "status": "Todo"
      },
      {
        "project": "MCP Server",
        "task_id": "TASK-002",
        "contexto": "Frontend",
        "descricao": "Tarefa 2",
        "prioridade": "Normal",