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

Install UV (if not already installed):

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

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:

Log in to your Goodday account
Go to Settings → API & Integrations
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:

Main API: http://localhost:8000
OpenAPI docs: http://localhost:8000/docs
Health check: http://localhost:8000/health
SSE endpoint: http://localhost:8000/sse
Available tools: http://localhost:8000/tools

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

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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues and questions:

GitHub Issues: https://github.com/your-username/goodday-ro-mcp/issues
Goodday API Documentation: https://developers.goodday.work

Goodday