QTask
Task/project MCP server with OAuth for Claude, Cursor bridge, semantic search, staged write approval
Dokümantasyon
QTask
Open-source task management with a built-in MCP server — connect Claude Desktop, Cursor, or any MCP client.
Works with: Claude Desktop · Cursor · Ollama (local agent)
Production: https://qtask.dev · MCP setup guide · User guide · Contribute on GitHub
- MCP server — list, create, and update tasks and projects from Claude Desktop, Cursor, or other MCP clients
- Staged writes — external AI proposes changes; you approve before they apply
- Semantic search — find tasks by meaning, not just keywords
- Self-hosted — your data stays on your infrastructure, with swappable AI backends (Ollama, MCP-compatible models)
Prerequisites
- Node.js 20+
- Docker (for MongoDB)
- Ollama with tool-capable models:
ollama pull qwen3.5:2b
ollama pull nomic-embed-text
If upgrading an existing install, set OLLAMA_MODEL=qwen3.5:2b in .env and pull the model above.
Quick start
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
- Web client: http://localhost:5173
Create an account on first visit. For local secrets (e.g. Resend API key), use .env.local — it overrides .env and is not committed. On the production server, put those values in .env instead (see docs/DEPLOY.md).
Documentation
| Doc | Audience |
|---|---|
| docs/MCP.md | External AI clients — start here for Claude Desktop & Cursor (API keys, OAuth, staging) |
| docs/USER_GUIDE.md | End users — projects, tasks, agent, sharing |
| docs/QTask_Product_Requirements.md | Product specification |
| docs/DEPLOY.md | Operators — local and production deployment |
In the web app, signed-in users can open Help from the account menu.
Scripts
| Command | Description |
|---|---|
npm run dev | Backend API only |
npm run dev:client | React web client only |
npm run dev:all | Backend + web client |
npm run mcp | MCP stdio server (local dev / Cursor) |
npm run mcp:bridge | Stdio bridge to hosted /api/mcp |
npm test | Run integration tests |
npm run build | Build API |
npm start | Start production API (serves web client) |
Authentication
Email/password accounts with JWT. All API routes except /health and /api/auth/* require Authorization: Bearer <token>.
MCP in Cursor
Log in via the web client, copy your JWT, and set MCP_JWT in your Cursor MCP config. See mcp-config.example.json.
For hosted qtask.dev, create an MCP API key in Account menu → External AI (MCP) and use npm run mcp:bridge. See docs/MCP.md.