Goodday MCP server

The Goodday MCP Server is a Model Context Protocol server that integrates with the Goodday project management platform. It provides a comprehensive set of tools for managing projects, tasks, and users through the Goodday API v2, allowing you to interact with your Goodday workspace programmatically.

Installation Options

Installing from PyPI

The recommended installation method is using PyPI:

pip install goodday-mcp

Installing from Source

Prerequisites

• Python 3.10 or higher
• UV package manager (recommended) or pip
• Goodday API token

Using UV

1. Install UV (if not already installed):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Clone and set up the project:

   git clone https://github.com/cdmx1/goodday-mcp.git
   cd goodday-mcp
   
   # Create virtual environment and install dependencies
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv sync
   

Using pip

git clone https://github.com/cdmx1/goodday-mcp.git
cd goodday-mcp
pip install -e .

Configuration

Set up your Goodday API token by creating a .env file or exporting as an environment variable:

export GOODDAY_API_TOKEN=your_goodday_api_token_here

To get your Goodday API token:

• Go to your Goodday organization
• Navigate to Settings → API
• Click the generate button to create a new token

Running the Server

Standalone Mode

If installed from PyPI:

goodday-mcp

If running from source with UV:

uv run goodday-mcp

Using with Claude Desktop

1. Configure Claude Desktop by editing your configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server configuration:

   If installed from PyPI:

   {
     "mcpServers": {
       "goodday": {
         "command": "goodday-mcp",
         "env": {
           "GOODDAY_API_TOKEN": "your_goodday_api_token_here"
         }
       }
     }
   }
   

   If running from source:

   {
     "mcpServers": {
       "goodday": {
         "command": "uv",
         "args": ["run", "goodday-mcp"],
         "env": {
           "GOODDAY_API_TOKEN": "your_goodday_api_token_here"
         }
       }
     }
   }
   

3. Restart Claude Desktop to load the new server.

Feature Overview

Project Management Tools

• Get projects with filtering options:

  # Get all active projects
  get_projects()
  
  # Get archived projects
  get_projects(archived=True)
  
  # Get only root-level projects
  get_projects(root_only=True)
  

• Get detailed project information:

  get_project(project_id="project_123")
  

• Create new projects:

  create_project(
      name="New Project",
      template_id="template_123",  # Optional
      color=5  # Optional (1-24)
  )
  

Task Management Tools

• Get tasks from a project:

  get_project_tasks(
      project_id="project_123",
      include_closed=False,  # Optional
      include_subfolders=True  # Optional
  )
  

• Get tasks assigned to a user:

  get_user_assigned_tasks(user_id="user_456")
  

• Create a new task:

  create_task(
      project_id="project_123",
      title="Implement new feature",
      from_user_id="user_456",
      message="Detailed description of the task",
      to_user_id="user_789",  # Optional
      deadline="2025-06-30",  # Optional
      priority=5  # Optional (1-10, 50=Blocker, 100=Emergency)
  )
  

• Update task status:

  update_task_status(
      task_id="task_123",
      user_id="user_456",
      status_id="status_completed",
      message="Task completed successfully"  # Optional
  )
  

• Add a comment to a task:

  add_task_comment(
      task_id="task_123",
      user_id="user_456",
      message="This is my comment on the task"
  )
  

User Management Tools

• Get all organization users:

  get_users()
  

• Get a specific user's details:

  get_user(user_id="user_123")
  

OpenWebUI Integration

The package includes an OpenWebUI tool that provides a chat interface for Goodday project management:

Setup

1. Copy openwebui/goodday_openwebui_complete_tool.py to your OpenWebUI tools directory
2. Configure the valves with your API credentials:
   • api_key: Your Goodday API token
   • search_url: Your VectorDB search endpoint (optional)
   • bearer_token: Bearer token for search API (optional)

Data Formats

Date Format

All dates should be provided in YYYY-MM-DD format (e.g., 2025-06-16).

Priority Levels

• 1-10: Normal priority levels
• 50: Blocker
• 100: Emergency

Project Colors

Project colors are specified as integers from 1-24, corresponding to Goodday's color palette.

Error Handling

The server includes comprehensive error handling for:

• Authentication errors (missing or invalid API token)
• Network errors (when Goodday API is unreachable)
• Validation errors (missing required parameters)
• Permission errors (insufficient user permissions)

All errors are returned as descriptive strings to help with troubleshooting.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "goodday" '{"command":"goodday-mcp","env":{"GOODDAY_API_TOKEN":"your_goodday_api_token_here"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "goodday": {
            "command": "goodday-mcp",
            "env": {
                "GOODDAY_API_TOKEN": "your_goodday_api_token_here"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "goodday": {
            "command": "goodday-mcp",
            "env": {
                "GOODDAY_API_TOKEN": "your_goodday_api_token_here"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect