Google Sheets Kanban MCP Server

MCP服务器-谷歌表格看板

MCP（模型上下文协议）服务器，用于管理使用 Google 表格作为后端的 Kanban 框架中的任务。

特点

• 与 Google Sheets 集成使用 Google Sheets API v4 进行数据存储
• pydantic模型使用 Pydantic v2 验证数据
• 批次操作支持同时添加和更新多个任务
• 高级搜索按优先级、状态、上下文、项目和文本进行过滤
• 分页全面支持结果分页导航
• MCP 协议通过STDIO与MCP客户端兼容

配置

克劳德

在工程文件夹中运行以下命令 ：

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

可用工具

1. get_one_task -Tarefa Específica巴士

按任务 ID 和工程名称查找特定任务 。

参数 ：

• project （必填）： 项目名称
• task_id （必填）： 唯一任务 ID

例如：

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

回报（成功）：

{
  "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": ""
}

返回（未找到）：

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

______________________________________________________________________

2. list_tasks 列出和搜索任务

列出并搜索具有高级过滤器和可选分页功能的电子表格任务。

参数 ：

• filters （可选）：具有搜索条件的对象

- prioridade优先级列表（ 低、 正常、 高、 紧急） - status：要筛选的状态列表 - contexto：按上下文过滤（部分搜索，不区分大小写） - projeto按项目过滤（部分搜索，近似不敏感） - texto_busca描述和详细搜索（case-insensitive） - task_id：按特定任务ID搜索 - sprint：按冲刺筛选

• pagination （可选）：COM对象 page （页码）和 page_size （每页项目）

例如：

// 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
  }
}

返回（不分页）：

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

返回（带分页）：

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

______________________________________________________________________

3. add_task - 添加任务

向工作表添加新任务 。

参数 ：

• task任务对象与所有字段

例如：

{
  "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 - 更新任务

以任务 ID 更新现有任务 。

参数 ：

• task_id: 要更新的任务 ID
• updates要更新的字段字典

例如：

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

______________________________________________________________________

5. batch_add_tasks - 添加多任务

在一个操作中添加多个任务。

参数 ：

• batch包含任务列表的 BatchTaskAdd 对象

例如：

{
  "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",
        "status": "Todo"
      }
    ]
  }
}

返回 ：

{
  "success_count": 2,
  "error_count": 0,
  "details": [
    {
      "task_id": "TASK-001",
      "status": "success",
      "message": "Tarefa adicionada com sucesso"
    },
    {
      "task_id": "TASK-002",
      "status": "success",
      "message": "Tarefa adicionada com sucesso"
    }
  ]
}

______________________________________________________________________

6. batch_update_tasks 多任务更新

在一次操作中更新多个任务。

参数 ：

• batch包含更新列表的 BatchTaskUpdate 对象

例如：

{
  "batch": {
    "updates": [
      {
        "task_id": "TASK-001",
        "fields": {"Status": "Concluído"}
      },
      {
        "task_id": "TASK-002",
        "fields": {"Prioridade": "Alta"}
      }
    ]
  }
}

返回 ：

{
  "success_count": 2,
  "error_count": 0,
  "details": [
    {
      "task_id": "TASK-001",
      "status": "success",
      "message": "Tarefa atualizada com sucesso"
    },
    {
      "task_id": "TASK-002",
      "status": "success",
      "message": "Tarefa atualizada com sucesso"
    }
  ]
}

______________________________________________________________________

7. get_valid_configs - 获取有效设置

返回有效的状态和优先级值。

返回 ：

{
  "valid_task_status": [
    "Todo",
    "Em Desenvolvimento",
    "Impedido",
    "Concluído",
    "Cancelado",
    "Não Relacionado",
    "Pausado"
  ],
  "valid_task_priorities": [
    "Baixa",
    "Normal",
    "Alta",
    "Urgente"
  ]
}

______________________________________________________________________

数据模型

任务

{
  "project": str,          # Nome do Projeto (obrigatório)
  "task_id": str,          # ID único da tarefa (obrigatório)
  "contexto": str,         # Contexto da tarefa (obrigatório)
  "descricao": str,        # Descrição breve (obrigatório)
  "prioridade": str,       # Prioridade (obrigatório)
  "status": str,           # Status atual (obrigatório)
  "task_id_root": str,     # ID da tarefa raiz (opcional)
  "sprint": str,           # Sprint associada (opcional)
  "detalhado": str,        # Descrição detalhada (opcional)
  "data_criacao": str,     # Data de criação (opcional)
  "data_solucao": str      # Data de solução (opcional)
}

BatchTaskAdd

{
  "tasks": List[Task]      # Lista de tarefas a serem adicionadas
}

BatchTaskUpdate

{
  "updates": List[TaskUpdate]  # Lista de atualizações
}

在哪里 任务更新 是 ：

{
  "task_id": str,          # ID da tarefa
  "fields": dict           # Campos a atualizar
}

搜索筛选器

{
  "prioridade": List[str],      # Lista de prioridades
  "status": List[str],          # Lista de status
  "contexto": str,              # Filtro de contexto
  "projeto": str,               # Filtro de projeto
  "texto_busca": str,           # Busca de texto
  "task_id": str,               # ID específico
  "sprint": str                 # Filtro de sprint
}

分页路径

{
  "page": int,           # Número da página (mínimo: 1)
  "page_size": int       # Itens por página (1-500)
}

考虑

{
  "tasks": List[Dict],   # Tarefas da página
  "total_count": int,    # Total de tarefas
  "page": int,           # Página atual
  "page_size": int,      # Itens por página
  "total_pages": int,    # Total de páginas
  "has_next": bool,      # Existe próxima página
  "has_previous": bool   # Existe página anterior
}

______________________________________________________________________

配置

先决条件

1. Python 3.13.5或更高级
2. 启用 Google Sheets API 的 Google Cloud 帐户
3. 档案 credentials.json 服务 帐户 凭据

环境变量

创建文件 .env 通用域名格式：

KANBAN_SHEET_ID=seu_id_da_planilha_aqui
KANBAN_SHEET_NAME=Back-End  # Nome da aba (padrão: "Back-End")

安装

# Instalar dependências
uv sync

# Executar servidor
uv run main.py

MCP 客户端配置

添加到您的 MCP 客户端：

{
  "mcpServers": {
    "kanban-sheets": {
      "command": "uv",
      "args": ["run", "main.py"]
    }
  }
}

______________________________________________________________________

电子表格结构

工作表必须有以下列（A 到 K）：

任务 ID 任务唯一 ID |C|根任务ID|根任务ID| | D | Sprint | Sprint 相关 | | 和 | 上下文 | 任务的上下文 | | F | 描述 | 简要描述 | | 详细 | 详细描述 | | H | 优先级 | 任务优先级 | |I |状态|状态自然| J 创建日期 创建日期 K 解决日期 解决日期

______________________________________________________________________

高级使用示例

查找所有紧急待办事宜

{
  "filters": {
    "prioridade": ["Urgente"],
    "status": ["Todo", "Em Desenvolvimento"]
  }
}

列出具有分页功能的特定项目的任务

{
  "filters": {
    "projeto": "MCP Server"
  },
  "pagination": {
    "page": 1,
    "page_size": 50
  }
}

查找已停止或暂停的任务

{
  "filters": {
    "status": ["Impedido", "Pausado"]
  }
}

在描述中搜索关键字

{
  "filters": {
    "texto_busca": "API REST"
  }
}

______________________________________________________________________

使用的技术

• FastMCPMCP 服务器框架
• 派丹蒂克数据验证（v2.12.3）
• Google API Python客户端与 Google Sheets 集成
• 谷歌认证使用 Google Cloud 进行身份验证

______________________________________________________________________

测试

该项目包括一个使用pytest的完整测试套件。

测试结构

tests/
├── __init__.py
├── conftest.py              # Fixtures compartilhadas
├── test_list_tasks.py       # Testes para listagem e busca
├── test_add_task.py         # Testes para adição de tarefas
├── test_update_task.py      # Testes para atualização
└── test_batch_operations.py # Testes para operações em lote

安装测试依赖项

# Instalar dependências de desenvolvimento
uv pip install -r requirements-dev.txt

依赖关系包括：

• pytest：测试框架
• pytest-asyncio支持异步测试
• pytest-cov：代码覆盖率
• pytest-mock模拟设施·全球之声

运行测试

# Executar todos os testes
uv run pytest

# Executar com cobertura de código
uv run pytest --cov

# Executar testes específicos
uv run pytest tests/test_list_tasks.py

# Executar testes com saída verbosa
uv run pytest -v

# Executar apenas testes de uma função específica
uv run pytest tests/test_list_tasks.py::test_list_tasks_all

# Gerar relatório de cobertura em HTML
uv run pytest --cov --cov-report=html
# O relatório será criado em htmlcov/index.html

测试结构

测试使用Google Sheets API模拟，以免依赖于实际连接。主要设备包括：

• mock_env_vars： 模拟环境变量
• mock_sheets_serviceGoogle Sheets 服务
• mock_credentials模仿 Google 凭据
• sample_sheet_data示例数据用于测试
• empty_sheet_data: 空工作表数据

测试覆盖

测试涵盖：

1. list_tasks:

- 无过滤器列表 - 个别过滤器（优先级、状态、上下文等） - 多个过滤器组合 - 分页 - 错误案例

1. add_task:

- 添加所有字段 - 添加最小字段 - 不同的优先级和状态 - 字段验证 - 错误处理

1. update_task:

- 更新单个字段 - 更新多个字段 - 状态和优先级验证 - 任务未找到 - 错误处理

1. batch_add_tasks和batchupdate_tasks:

- 成功批次操作 - 部分成功的操作 - 批量验证 - 错误处理

1. get_valid_config:

- 返回有效设置 - 回报结构

测试示例

def test_list_tasks_with_priority_filter(mock_env_vars, mock_credentials_file,
                                         mock_credentials, mock_get_sheets_service):
    """Testa filtro por prioridade."""
    filters = SearchFilters(prioridade=["Alta"])
    result = list_tasks(filters=filters)

    assert isinstance(result, list)
    assert len(result) == 1
    assert result[0]["Task ID"] == "TASK-001"
    assert result[0]["Prioridade"] == "Alta"

pytest 配置

文件 pytest.ini 包含默认设置，包括：

• 测试发现标准
• 输出选项
• 代码覆盖设置
• 自定义标记

______________________________________________________________________

附加文档

• 迁移到 Pydantic
• 谷歌网页API
• 模型上下文协议

______________________________________________________________________

许可证

此项目是用于管理 Google 工作表中的任务的 MCP 服务器。