PomoDash MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to PomoDash for seamless task and project management.

Features

• Task Management: Create, list, update, and delete tasks with the PomoDash productivity app
• Notes System: Create and manage notes linked to tasks/projects
• Categories & Projects: Organize your work with categories and projects
• Secure Authentication: API key-based authentication with rate limiting
• Docker Support: Easy deployment with Docker and Docker Compose
• AI Integration: Works with all MCP-compatible clients (Claude Desktop, VS Code, Cursor, etc.)

Prerequisites

• Premium PomoDash Account: MCP integration requires a premium subscription
• API Key: Generate an API key in PomoDash Settings → API Keys
• Node.js 20+ (for local development) or Docker (for containerized deployment)

Quick Start with Docker Desktop

1. Generate API Key in PomoDash

1. Open PomoDash in your browser and log in
2. Navigate to Settings → Click on your profile → Settings
3. Go to API Keys section → Look for "API Keys" in the settings menu
4. Click "Generate New Key" → This creates a new API key for MCP access
5. Copy the key immediately → Format looks like pmk_abc123...
6. ⚠️ Important: You can only see this key once! Save it somewhere safe.

2. Setup Environment File

1. Download this repository or clone it to your computer
2. Navigate to the pomodash-mcp-server folder
3. Find the file .env.example in the folder
4. Make a copy and rename it to .env (remove the .example part)
5. Open the .env file with any text editor (Notepad, TextEdit, VS Code, etc.)
6. Replace pmk_your_api_key_here with your actual API key from step 1
7. Save the file

Your .env file should look like this:

POMODASH_API_KEY=pmk_abc123your_real_key_here
POMODASH_API_URL=https://mcp.pomodash.mindsnapz.de
NODE_ENV=production

3. Using Docker Desktop App

Option A: Using Docker Compose (Easiest)

1. Open Docker Desktop application on your computer
2. Make sure Docker Desktop is running (you'll see the Docker whale icon)
3. Open Terminal/Command Prompt and navigate to the pomodash-mcp-server folder
4. Run the command: docker-compose up --build
5. Go back to Docker Desktop → You'll see a new container called "pomodash-mcp-server"
6. The container is now running! You can see logs, stop/start it from Docker Desktop

Option B: Build and Run Manually in Docker Desktop

1. Open Docker Desktop application
2. Open Terminal and navigate to the pomodash-mcp-server folder
3. Build the image: docker build -t pomodash-mcp-server .
4. Go to Docker Desktop → Images tab → You'll see "pomodash-mcp-server"
5. Click the "Run" button next to the image
6. In the run dialog:
   • Click "Optional Settings"
   • Go to "Environment variables"
   • Add: POMODASH_API_KEY = your_api_key
   • Add: POMODASH_API_URL = https://mcp.pomodash.mindsnapz.de
   • Check "Interactive" and "TTY" options
7. Click "Run" → Container starts and appears in Containers tab

4. Verify It's Working

1. In Docker Desktop, go to Containers tab
2. Find "pomodash-mcp-server" container
3. Click on it to see details
4. Look at the "Logs" tab → Should show "PomoDash MCP Server running on stdio"
5. If you see errors, check that your API key is correct and your PomoDash account is Premium

Local Development

Setup

# Install dependencies
npm install

# Build TypeScript
npm run build

# Start in development mode
npm run dev

Run the server

# With environment variables set
POMODASH_API_KEY=pmk_your_key node dist/index.js

# Or with .env file
npm start

MCP Client Configuration

Docker Configuration (All MCP Clients)

Add this to your MCP client's configuration file:

{
  "mcpServers": {
    "pomodash": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "POMODASH_API_KEY=pmk_your_api_key_here",
        "mcp/pomodash"
      ]
    }
  }
}

Configuration File Locations

Claude Desktop:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Other MCP Clients:

• Most MCP clients use similar JSON configuration
• Check your client's documentation for the exact file location
• The configuration format above works universally

Alternative: Local Node.js Setup (Without Docker)

If you prefer not to use Docker:

1. Build the project: npm run build in the pomodash-mcp-server folder
2. Use this config instead:

{
  "mcpServers": {
    "pomodash": {
      "command": "node",
      "args": ["/full/path/to/pomodash-mcp-server/dist/index.js"],
      "env": {
        "POMODASH_API_KEY": "pmk_your_api_key_here",
        "POMODASH_API_URL": "https://mcp.pomodash.mindsnapz.de"
      }
    }
  }
}

Quick Start

Using Docker (Recommended)

1. Generate PomoDash API Key

   • Open PomoDash → Settings → API Keys
   • Click "Generate New Key" (Premium account required)
   • Copy the key (format: pmk_...)

2. Run with Docker

   docker run --rm -i \
     -e POMODASH_API_KEY=pmk_your_api_key_here \
     mcp/pomodash

3. Configure AI Assistant

   • Add to your MCP client configuration (see examples below)

Docker Desktop MCP Toolkit

If you have Docker Desktop with MCP Toolkit enabled:

1. Search for "PomoDash" in MCP Catalog
2. Click "Install"
3. Enter your API key
4. Connect to your AI assistant

Manual Setup

Available Tools

The MCP server provides these tools to AI assistants:

Tasks

• create_task - Create a new task
• list_tasks - List all tasks
• update_task - Update an existing task
• delete_task - Delete a task
• create_task_for_project - Create a task linked to a project

Notes

• create_note - Create a new note
• list_notes - List all notes
• update_note - Update an existing note
• delete_note - Delete a note

Categories & Projects

• list_categories - List all categories and projects
• create_category - Create a new category or project

Environment Variables

Variable	Required	Default	Description
POMODASH_API_KEY	✅	-	Your PomoDash API key
POMODASH_API_URL	❌	https://mcp.pomodash.mindsnapz.de	API base URL
NODE_ENV	❌	-	Node environment

Testing

Test Docker Build

./test-docker.sh

Manual Testing

# Test API connection
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://mcp.pomodash.mindsnapz.de/tasks

# Test container health
docker ps
docker logs pomodash-mcp-server

Troubleshooting

Common Issues

"POMODASH_API_KEY environment variable is required"

• Ensure your .env file contains a valid API key
• Check that the key format starts with pmk_

"401 Invalid API key"

• Verify your API key is correct and active
• Check if your premium subscription is active

"403 Premium required"

• Upgrade to a premium PomoDash account
• Verify your subscription status in account settings

"429 Rate limit exceeded"

• You've hit the daily API limit
• Wait for the daily reset or contact support

Container won't start

• Check Docker logs: docker logs pomodash-mcp-server
• Verify .env file exists and contains valid values
• Ensure Docker has sufficient resources

Docker Debugging

# View container logs
docker-compose logs -f pomodash-mcp-server

# Check container status
docker-compose ps

# Rebuild from scratch
docker-compose down
docker-compose build --no-cache
docker-compose up

Security

• Never commit API keys to version control
• Rotate keys regularly in PomoDash settings
• Use environment variables for sensitive data
• Keep Docker images updated for security patches

What is PomoDash?

PomoDash is a modern productivity application that combines the Pomodoro Technique with advanced task management. Built for professionals who want to:

• Focus Better: Use proven Pomodoro timers to maintain concentration
• Organize Tasks: Advanced project and category management
• Track Progress: Detailed analytics and productivity insights
• Stay Motivated: Gamification elements and streak tracking
• Work Anywhere: Cross-platform with real-time sync

Try PomoDash →

Support

For issues related to:

• MCP Server: Check this repository's issues
• PomoDash App: Visit PomoDash
• MCP Protocol: See Model Context Protocol docs