QTask
Servidor MCP de tarefas/projetos com OAuth para Claude, ponte Cursor, busca semântica, aprovação de escrita em etapas
Documentação
QTask
Gerenciamento de tarefas de código aberto com um servidor MCP integrado — conecte Claude Desktop, Cursor ou qualquer cliente MCP.
Funciona com: Claude Desktop · Cursor · Ollama (agente local)
Produção: https://qtask.dev · Guia de configuração do MCP · Guia do usuário · Contribua no GitHub
- Servidor MCP — liste, crie e atualize tarefas e projetos a partir do Claude Desktop, Cursor ou outros clientes MCP
- Gravações em etapas — a IA externa propõe alterações; você aprova antes que sejam aplicadas
- Pesquisa semântica — encontre tarefas pelo significado, não apenas por palavras-chave
- Auto-hospedado — seus dados permanecem na sua infraestrutura, com backends de IA intercambiáveis (Ollama, modelos compatíveis com MCP)
Pré-requisitos
- Node.js 20+
- Docker (para MongoDB)
- Ollama com modelos capazes de usar ferramentas:
ollama pull qwen3.5:2b
ollama pull nomic-embed-text
Se estiver atualizando uma instalação existente, defina OLLAMA_MODEL=qwen3.5:2b em .env e baixe o modelo acima.
Início rápido
docker compose up -d
cp .env.example .env
# Set JWT_SECRET in .env
# Optional: cp .env.local.example .env.local # secrets / overrides (gitignored)
npm install
npm install --prefix client
npm run dev:all
- API: http://localhost:3000
- Cliente web: http://localhost:5173
Crie uma conta na primeira visita. Para segredos locais (por exemplo, chave de API do Resend), use .env.local — ele substitui .env e não é commitado. No servidor de produção, coloque esses valores em .env em vez disso (veja docs/DEPLOY.md).
Documentação
| Doc | Público |
|---|---|
| docs/MCP.md | Clientes de IA externos — comece aqui para Claude Desktop e Cursor (chaves de API, OAuth, staging) |
| docs/USER_GUIDE.md | Usuários finais — projetos, tarefas, agente, compartilhamento |
| docs/QTask_Product_Requirements.md | Especificação do produto |
| docs/DEPLOY.md | Operadores — implantação local e em produção |
No aplicativo web, usuários conectados podem abrir Ajuda no menu da conta.
Scripts
| Comando | Descrição |
|---|---|
npm run dev | Somente API de backend |
npm run dev:client | Somente cliente web React |
npm run dev:all | Backend + cliente web |
npm run mcp | Servidor MCP stdio (desenvolvimento local / Cursor) |
npm run mcp:bridge | Ponte stdio para /api/mcp hospedado |
npm test | Executar testes de integração |
npm run build | Compilar API |
npm start | Iniciar API de produção (serve o cliente web) |
Autenticação
Contas por e-mail/senha com JWT. Todas as rotas de API, exceto /health e /api/auth/*, exigem Authorization: Bearer <token>.
MCP no Cursor
Faça login pelo cliente web, copie seu JWT e defina MCP_JWT na configuração MCP do Cursor. Veja mcp-config.example.json.
Para qtask.dev hospedado, crie uma chave de API MCP no menu Conta → IA Externa (MCP) e use npm run mcp:bridge. Veja docs/MCP.md.