Goodday

A read-only server for the Goodday project management platform.

GitHub

Goodday Read-Only MCP Server

A read-only Model Context Protocol (MCP) server for integrating with Goodday project management platform. This server provides read-only tools for querying projects, tasks, and users through the Goodday API v2, ensuring no data can be modified.

Features

Project Management (Read-Only)

  • get_projects: Retrieve list of projects (with options for archived and root-only filtering)
  • get_project: Get detailed information about a specific project
  • get_project_users: Get users associated with a specific project

Task Management (Read-Only)

  • get_project_tasks: Retrieve tasks from specific projects (with options for closed tasks and subfolders)
  • get_user_assigned_tasks: Get tasks assigned to a specific user
  • get_user_action_required_tasks: Get action-required tasks for a user
  • get_task: Get detailed information about a specific task

User Management (Read-Only)

  • get_users: Retrieve list of organization users
  • get_user: Get detailed information about a specific user

Installation

From PyPI (Recommended)

pip install goodday-ro-mcp

From Source

Prerequisites

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

Setup with 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/your-username/goodday-ro-mcp.git
cd goodday-ro-mcp
uv sync

Setup with pip

git clone https://github.com/your-username/goodday-ro-mcp.git
cd goodday-ro-mcp
pip install -e .

Configuration

Environment Variables

Set your Goodday API token as an environment variable:

export GOODDAY_API_TOKEN="your_goodday_api_token_here"

Finding your API token:

  1. Log in to your Goodday account
  2. Go to Settings → API & Integrations
  3. Generate or copy your API token

Usage

As MCP Server (Claude Desktop)

Add to your Claude Desktop config file:

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

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

As HTTP Server (Docker)

You can also run this as a standalone HTTP server with OpenAPI documentation and Server-Sent Events support:

# Run directly
goodday-ro-mcp-server

# Or with Docker (see Docker section below)
docker run -e GOODDAY_API_TOKEN=your_token -p 8000:8000 goodday-ro-mcp:latest

The server will be available at:

Docker Deployment

Build Docker Image

cd goodday-ro-mcp
docker build -t goodday-ro-mcp:latest .

Run with Docker

docker run -d \
  --name goodday-ro-mcp \
  -e GOODDAY_API_TOKEN=your_goodday_api_token_here \
  -p 8000:8000 \
  goodday-ro-mcp:latest

Run with Docker Compose

version: '3.8'
services:
  goodday-ro-mcp:
    build: .
    environment:
      - GOODDAY_API_TOKEN=${GOODDAY_API_TOKEN}
    ports:
      - "8000:8000"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

API Endpoints

When running as an HTTP server, the following endpoints are available:

Core Endpoints

  • GET / - Server information and available tools
  • GET /health - Health check endpoint
  • GET /tools - List of available tools with descriptions
  • POST /tools/call - Execute a tool with arguments
  • GET /sse - Server-Sent Events for real-time updates
  • GET /docs - OpenAPI documentation (Swagger UI)

Example API Usage

# Get all projects
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "get_projects", "arguments": {"archived": false, "root_only": true}}'

# Get specific project
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "get_project", "arguments": {"project_id": "12345"}}'

# Get project tasks
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "get_project_tasks", "arguments": {"project_id": "12345", "closed": false}}'

Available Tools

All tools are read-only and will not modify any data in your Goodday account.

Project Tools

  • get_projects(archived=False, root_only=False) - List projects
  • get_project(project_id) - Get project details
  • get_project_users(project_id) - Get project team members

Task Tools

  • get_project_tasks(project_id, closed=False, subfolders=False) - List project tasks
  • get_task(task_id) - Get task details
  • get_user_assigned_tasks(user_id, closed=False) - Get user's assigned tasks
  • get_user_action_required_tasks(user_id) - Get user's action required tasks

User Tools

  • get_users() - List organization users
  • get_user(user_id) - Get user details

Error Handling

The server includes comprehensive error handling:

  • API Errors: Goodday API errors are caught and returned with descriptive messages
  • Network Errors: Connection timeouts and network issues are handled gracefully
  • Authentication Errors: Missing or invalid API tokens are reported clearly
  • Data Validation: Invalid responses from the API are handled safely

Development

Running Tests

uv run pytest

Code Formatting

uv run black goodday_ro_mcp/
uv run isort goodday_ro_mcp/

Type Checking

uv run mypy goodday_ro_mcp/

Security

This is a read-only server that:

  • Only makes GET requests to the Goodday API
  • Cannot create, update, or delete any data
  • Validates all inputs to prevent injection attacks
  • Uses secure HTTP headers and CORS policies

Limitations

  • Read-Only: Cannot create, update, or delete projects, tasks, or users
  • Rate Limiting: Subject to Goodday API rate limits
  • Authentication: Requires a valid Goodday API token
  • Permissions: Limited to data accessible by the API token's associated user

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Support

For issues and questions:

Related Servers