taskdog-mcp

MCP (Model Context Protocol) server for Taskdog, enabling Claude Desktop and other MCP-compatible AI clients to interact with your task management system.

Features

• Task Management: Create, read, update, delete tasks via natural language
• Task Lifecycle: Start, complete, pause, cancel, reopen tasks
• Task Decomposition: AI-assisted breakdown of large tasks into subtasks
• Queries: Get statistics, executable tasks, tag statistics

Installation

# From the taskdog workspace root
make install-mcp

# Or install globally
uv tool install taskdog-mcp

Configuration

Create ~/.config/taskdog/mcp.toml:

[api]
host = "127.0.0.1"
port = 8000
api_key = ""  # Optional, for authenticated servers
# base_url = "https://tasks.example.com"  # Overrides host/port (HTTPS, reverse proxy)

[server]
name = "taskdog"
log_level = "INFO"

Environment variables override config file:

• TASKDOG_API_HOST
• TASKDOG_API_PORT
• TASKDOG_API_KEY
• TASKDOG_API_BASE_URL
• TASKDOG_MCP_NAME
• TASKDOG_MCP_LOG_LEVEL

Claude Desktop Setup

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "taskdog": {
      "command": "taskdog-mcp"
    }
  }
}

Or with uv (for development):

{
  "mcpServers": {
    "taskdog": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/taskdog/packages/taskdog-mcp",
        "run",
        "taskdog-mcp"
      ]
    }
  }
}

Available Tools

Task CRUD

• list_tasks - List tasks with filtering
• get_task - Get task details
• create_task - Create a new task
• update_task - Update task fields
• delete_task - Delete/archive a task
• restore_task - Restore an archived task

Lifecycle

• start_task - Start working on a task
• complete_task - Mark task as completed
• pause_task - Pause a task
• cancel_task - Cancel a task
• reopen_task - Reopen a completed/canceled task

Queries

• get_statistics - Get task statistics
• get_tag_statistics - Get tag statistics
• get_executable_tasks - Get tasks AI can work on

Decomposition & Organization

• decompose_task - Break down a task into subtasks
• add_dependency - Add dependency between tasks
• remove_dependency - Remove a dependency
• set_task_tags - Set task tags
• update_task_notes - Update task notes
• get_task_notes - Get task notes

Usage Examples

Ask Claude Desktop:

• "Create a task to write unit tests for the API"
• "Start task 42"
• "Complete task 42"
• "Decompose task 123 into smaller subtasks for implementing the login feature"
• "What tasks can you execute for me?"

Requirements

• taskdog-server must be running (default: http://127.0.0.1:8000)
• Python 3.13+

Development

# Install in development mode
cd packages/taskdog-mcp
uv pip install -e .

# Run tests
PYTHONPATH=src uv run python -m pytest tests/ -v

Troubleshooting

"Cannot connect to API server"

Problem: MCP server can't reach taskdog-server

Solutions:

1. Check if taskdog-server is running:

   curl http://127.0.0.1:8000/health
   

2. Verify ~/.config/taskdog/mcp.toml has correct host/port

3. Check if authentication is required:

   curl -H "X-Api-Key: your-key" http://127.0.0.1:8000/health
   

"Authentication failed"

Problem: API key is invalid or missing

Solutions:

1. Ensure api_key in mcp.toml matches a key in server.toml
2. Check that auth is enabled on server ([auth] enabled = true)

Claude Desktop doesn't see taskdog tools

Problem: MCP server not properly configured

Solutions:

1. Verify claude_desktop_config.json has correct path
2. Restart Claude Desktop after config changes
3. Check logs: ~/Library/Logs/Claude/mcp*.log (macOS)

Related Packages

• taskdog-server: Required API server
• taskdog-core: Core business logic
• taskdog-client: HTTP client used internally

License

MIT