dizlexic/moo-tasks

Moo Tasks

mootasks.dev

A kanban-style task management dashboard with an integrated MCP server. Human users manage tasks via a drag-and-drop web UI, while AI agents connect via the MCP server to discover, accept, update, and create tasks programmatically.

---

✨ Features

Screenshots

---

💾 Board Management

• Import Board: Available on the Dashboard page.
• Export Board: Available in the Board Settings panel.

---

🚀 Quick Start

The quickest way to run a local instance is Docker Compose. This starts the app, MySQL, and development-only Adminer and Mailpit services.

🐳 Run locally with Docker Compose

Prerequisites: Docker Desktop or Docker Engine with the Compose v2 plugin.

git clone https://github.com/dizlexic/moo-agent-board.git
cd moo-agent-board
cp .env.example .env

Before starting, edit .env and replace NUXT_SESSION_PASSWORD, DB_ROOT_PASSWORD, and DB_PASSWORD with unique secrets. Generate a secret with openssl rand -hex 32; use a different value for each password. The session password must be at least 32 characters. The example database credentials are for local development only—never expose them to the internet.

Start the stack:

docker compose up --build -d
docker compose logs -f app

The app is at http://localhost:3000. Register an account to create your first board. The container waits for MySQL and runs database migrations on startup; the first start can take a few minutes. Adminer (http://localhost:8080) and the Mailpit inbox (http://localhost:8025) are for local development only. To log into Adminer, select MySQL, use db as the server, and enter DB_USER and DB_PASSWORD from .env. Mailpit captures outgoing messages so you can inspect them without sending real email.

MySQL data is stored in the db-data Docker volume. docker compose down stops the services without removing data; docker compose down -v deletes the database volume and all its data.

🛠️ Run the app from source

For development, install Node.js v26.13.0 (see .nvmrc), npm, and MySQL 8. Copy .env.example to .env, configure the database connection and a 32-character-or-longer NUXT_SESSION_PASSWORD, then install dependencies with npm ci. Set DATABASE_URL to your MySQL connection string; npm run db:migrate applies migrations, and npm run dev starts the app. If using the Compose Mailpit service from your host, set SMTP_HOST=localhost and SMTP_PORT to MAILPIT_SMTP_PORT (default 1025).

📖 Usage Guide

Get up and running in just a few minutes:

1. Launch: Once the server is running, navigate to http://localhost:3000 (or the live site at mootasks.dev).
2. Account: Register your account at /register or login.
3. Create Board: Head to the Dashboard to create your first project board.
4. Manage Tasks: Add, move, and update tasks on your new board using the drag-and-drop Kanban view or the list view.
5. Connect AI: Go to Board Settings to view your MCP configuration and connect your favorite AI agent (e.g., Claude Code, Cursor, VS Code).
6. Seed Data: Need test data? Run npx tsx server/db/seed.ts to populate the database with sample tasks.

---

⚙️ Environment Variables

Copy .env.example to .env and adjust for your environment. Compose supplies its own internal database URL and uses the db service name; when running the app directly on your host, use localhost and the published database port instead.

When running the app on the host against the Compose database, use DB_HOST=localhost and set DB_PORT to DB_LOCAL_PORT (default 3307). Set BASE_URL to the public origin and configure a real SMTP provider before sending email from a deployed instance. See Self-hosting and production setup before exposing an instance to the internet.

---

🤖 MCP Server

Moo Tasks is primarily an MCP server and Agent API. While it provides a web interface for humans, its core purpose is to enable AI agents to manage tasks programmatically.

🎯 Board-Scoped Architecture

Everything in Moo Tasks is scoped to a board. There are no global queries for tasks. This ensures that agents only work within the context they are assigned to, improving focus and security.

• Each board has its own unique MCP endpoint.
• AI agents connect to a specific board to work on its tasks.
• Resources, prompts, and tools are all scoped to the active board.

📋 Working with Tasks via MCP

The board acts as the primary task list for this application. To programmatically work on tasks:

1. Get the MCP Token: In the Board Settings, generate an MCP token if the board is private.
2. Configure Your Agent: Add the MCP server configuration for your specific board.
3. Use Tools: Use the available tools (list-tasks, accept-task, update-task-status, etc.) to interact with the tasks.

🔐 Security & Privacy

Tokens can be generated, rotated, or revoked at any time from Board Settings.

🛠️ Tools

📚 Resources

💬 Prompts

---

🔄 Task Hierarchy & Corrections

Moo Tasks supports a refined workflow for task completion:

• Review Status — Move tasks to “Review” when ready for human verification
• Request Corrections — From “Review” or “Done”, create linked “Correction Tasks”
• Linked Navigation — Correction tasks link to their parent for easy navigation

Configurable Instructions

Both support reset to default to restore the original built-in instructions.

---

🔌 MCP Client Configuration

---

📡 API Routes

---

☁️ Deploy your own instance

The Compose stack above is for local use, not production: it publishes development tools and uses a local database volume. For a production checklist covering hosting, secrets, database, email, and migrations, see Self-hosting and production setup. A DigitalOcean App Platform example is available in .do/app.yaml; the GitHub Actions workflow only builds the project and does not deploy it.

---

🧱 Tech Stack

---

Built with 🐄 by dizlexic