MCP Task Management

Standalone server based on the Model Context Protocol (MCP) to integrate development agents with the Task Management system.

Requirements

• Node.js 22.5 or higher;

• access to the Task Management server;

• valid credentials or an authentication token.

Related MCP server: Cherry Studio Task Board

Installation

npm install
npm run build

Configuration and authentication

The assistant configures the server URL and authentication locally. The URL can be provided via the GESTAO_TAREFAS_API_URL variable, the --api-url argument, or during the assistant's execution.

npm run setup

When the URL is not configured, the assistant will prompt:

URL do Gestão de Tarefas:

It is also possible to provide access data via arguments:

npm run setup -- \
  --api-url=https://seu-servidor-de-gestao.exemplo \
  --email=seu.email@empresa.gov.br \
  --password=suasenha

To use an existing web session or token:

npm run setup -- --api-url=https://seu-servidor-de-gestao.exemplo --token=SEU_TOKEN

The assistant attempts to authenticate via a JSON endpoint and, if not available, uses the web form with CSRF. Credentials are not versioned. The session or token is saved in the local .env and in ~/.gestao-tarefas-mcp/config.json.

An existing web session or token can be provided to the assistant or configured in GESTAO_TAREFAS_API_TOKEN.

Environment variables

The .env.example file contains the reference configuration:

GESTAO_TAREFAS_API_URL=https://seu-servidor-de-gestao.exemplo
GESTAO_TAREFAS_API_TOKEN=cole_a_sessao_web_ou_token_aqui
OFFLINE_QUEUE_PATH=~/.gestao-tarefas-mcp/queue.sqlite
REQUEST_TIMEOUT_MS=5000
IGNORE_PREFEITURA=true
IGNORED_PROJECT_PATTERNS=prefeitura,pmsp,pref-,pm-,pm_

Do not place tokens, passwords, or cookies in versioned files.

Features

The server provides tools for:

• detecting the current project and its link to the system;

• listing projects, demands, and sprints;

• creating demands and subtasks;

• updating subtasks and querying demand details;

• associating demands with sprints;

• operating with an offline queue and syncing items later;

• checking connectivity and authentication status.

Projects marked as external or belonging to the City Hall can be automatically ignored. This behavior is controlled by IGNORE_PREFEITURA, IGNORED_PROJECT_PATTERNS, and the .gestaotarefas.json file.

Execution

The server uses stdio and must be run from the build:

npm run build
node dist/index.js

Example configuration for an MCP client:

{
  "mcpServers": {
    "gestao-tarefas": {
      "command": "node",
      "args": ["/caminho/para/mcp-gestao-tarefas/dist/index.js"],
      "env": {
        "GESTAO_TAREFAS_API_URL": "https://seu-servidor-de-gestao.exemplo",
        "GESTAO_TAREFAS_API_TOKEN": "CONFIGURADO_LOCALMENTE",
        "OFFLINE_QUEUE_PATH": "~/.gestao-tarefas-mcp/queue.sqlite",
        "IGNORE_PREFEITURA": "true"
      }
    }
  }
}

After changing the code, run npm run build and restart the MCP client.

The component and flow overview is in ARCHITECTURE.md.

Development agent configuration

An agent with workspace access can configure the server following this sequence:

Configure o servidor MCP deste projeto.

1. Leia o README.md e identifique o cliente MCP em uso.
2. Use o diretório atual como diretório do projeto.
3. Instale as dependências apenas se necessário.
4. Execute npm run build.
5. Registre o servidor usando node dist/index.js e preserve as demais
   configurações existentes do cliente.
6. Solicite a URL do servidor e a autenticação caso ainda não estejam
   configuradas. Não exiba nem grave tokens ou senhas no chat.
7. Inicie o servidor ou informe que o cliente precisa ser reiniciado.

The agent must ask for confirmation before overwriting existing configurations or installing dependencies. If it does not have permission to change the client configuration, it must provide instructions for manual application.

Project configuration

The .gestaotarefas.json file must be created at the root of the repository that will be integrated with Task Management, at the same level as the .git directory:

meu-projeto/
├── .git/
├── .gestaotarefas.json
├── package.json
└── src/

The MCP looks for this file starting from the current directory and continues going up through parent folders. Thus, a configuration placed in a common folder can also be shared by multiple repositories. The alternative name .gestao-tarefas.json is also accepted.

To link the repository to a project, create meu-projeto/.gestaotarefas.json with the corresponding identifier:

{
  "projeto_id": 1,
  "nome": "Gestão de Tarefas",
  "departamento": "TI"
}

To disable the MCP only in this repository, use the same file:

{
  "nome": "Projeto externo",
  "tipo": "externo",
  "ignorado": true,
  "motivo": "Projeto fora do escopo"
}

Tests

npm test

The suite covers authentication, context detection, bypass of ignored projects, HTTP communication, offline queue, synchronization, and MCP tools.