The Goodday MCP Server enables comprehensive integration with the Goodday project management platform through a complete set of tools for managing projects, tasks, sprints, users, and documents.
Project Management: Retrieve, filter, and create projects with customizable templates, settings, colors, owners, and dates. View project details and associated users.
Task Management: Get tasks from projects (including closed tasks and subfolders), retrieve tasks assigned to users or requiring their action, obtain detailed task information with subtasks and metadata, create fully customizable tasks with assignments and priorities, update task statuses, and add comments.
Sprint Management: Fetch tasks from specific sprints and generate comprehensive sprint summaries with task details, status distribution, and key metrics.
User Management: Retrieve organization users and get detailed user information.
Smart Query & Search: Use natural language interface for project management queries, perform semantic search across tasks using VectorDB backend, search for documents within projects, and retrieve full document content.
Integration: Supports OpenWebUI, Claude Desktop, and other MCP-compatible clients with environment variable configuration for API tokens.
Supports loading environment variables from a .env file for configuring the API token needed to authenticate with Goodday.
Provides a workflow for extracting Goodday task data, creating embeddings using Ollama, and storing them in a Qdrant vector database for semantic search functionality.
Used within the n8n workflow to create embeddings for Goodday tasks, enabling semantic search capabilities for the MCP server.
Provides the runtime environment for the MCP server, requiring Python 3.10 or higher for operation.
Goodday MCP Server
A Model Context Protocol (MCP) server for integrating with Goodday project management platform. This server provides tools for managing projects, tasks, and users through the Goodday API v2.
Features
Project Management
get_projects: Retrieve list of projects (with options for archived and root-only filtering)
get_project: Get detailed information about a specific project
create_project: Create new projects with customizable templates and settings
get_project_users: Get users associated with a specific project
Task Management
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
get_task_details: Get comprehensive task details including subtasks, custom fields, and full metadata
get_task_messages: Retrieve all messages/comments for a specific task
create_task: Create new tasks with full customization (subtasks, assignments, dates, priorities)
update_task_status: Update task status with optional comments
add_task_comment: Add comments to tasks
Sprint Management
get_goodday_sprint_tasks: Get tasks from specific sprints by project name and sprint name/number
get_goodday_sprint_summary: Generate comprehensive sprint summaries with task details, status distribution, and key metrics
User Management
get_users: Retrieve list of organization users
get_user: Get detailed information about a specific user
Smart Query & Search
get_goodday_smart_query: Natural language interface for common project management queries
search_goodday_tasks: Semantic search across tasks using VectorDB backend
search_project_documents: Search for documents within specific projects
get_document_content: Retrieve full content of specific documents
OpenWebUI Integration
This package also includes an OpenWebUI tool that provides a complete interface for Goodday project management directly in chat interfaces. The OpenWebUI tool includes:
Features
Project Management: Get projects, project tasks, and project details
Sprint Management: Get tasks from specific sprints by name/number, comprehensive sprint summaries
User Management: Get tasks assigned to specific users, user details
Task Details: Get comprehensive task information including subtasks, custom fields, and metadata
Task Messages: Retrieve all messages and comments for tasks
Smart Query: Natural language interface for common project management requests
Semantic Search: Search across tasks using VectorDB backend with embeddings
Document Management: Search project documents and retrieve document content
Advanced Filtering: Support for archived projects, closed tasks, subfolders, and more
Setup
Copy
openwebui/goodday_openwebui_complete_tool.py
to your OpenWebUI tools directoryConfigure the valves with your API credentials:
api_key
: Your Goodday API tokensearch_url
: Your VectorDB search endpoint (optional)bearer_token
: Bearer token for search API (optional)
Vector Database Setup (Optional)
For semantic search functionality, you can set up a vector database using the provided n8n workflow (openwebui/n8n-workflow-goodday-vectordb.json
). This workflow:
Fetches all Goodday projects and tasks
Extracts task messages and content
Creates embeddings using Ollama
Stores in Qdrant vector database
Provides search API endpoint
See openwebui/OPENWEBUI_TOOL_README.md
for detailed usage instructions.
Installation
From PyPI (Recommended)
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 | shClone 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
Setup with pip
Configuration
Set up environment variables: Create a
.env
file in your project root or export the variable:export GOODDAY_API_TOKEN=your_goodday_api_token_hereTo get your Goodday API token:
Go to your Goodday organization
Navigate to Settings → API
Click the generate button to create a new token
Usage
Running the Server Standalone
If installed from PyPI:
If running from source with UV:
Using with Claude Desktop
Configure Claude Desktop by editing your configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Add the server configuration:
Option A: If installed from PyPI:
{ "mcpServers": { "goodday": { "command": "goodday-mcp", "env": { "GOODDAY_API_TOKEN": "your_goodday_api_token_here" } } } }Option B: If running from source:
{ "mcpServers": { "goodday": { "command": "uv", "args": ["run", "goodday-mcp"], "env": { "GOODDAY_API_TOKEN": "your_goodday_api_token_here" } } } }Restart Claude Desktop to load the new server.
Using with Other MCP Clients
The server communicates via stdio transport and can be integrated with any MCP-compatible client. Refer to the MCP documentation for client-specific integration instructions.
API Reference
Environment Variables
Variable | Description | Required |
| Your Goodday API token | Yes |
Tool Examples
Get Projects
Create a Task
Update Task Status
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:
Authentication errors: When API token is missing or invalid
Network errors: When Goodday API is unreachable
Validation errors: When required parameters are missing
Permission errors: When user lacks permissions for requested operations
All errors are returned as descriptive strings to help with troubleshooting.
Development
Project Structure
Adding New Tools
To add new tools to the server:
Add the tool function in
goodday_mcp/main.py
using the@mcp.tool()
decorator:@mcp.tool() async def your_new_tool(param1: str, param2: Optional[int] = None) -> str: """Description of what the tool does. Args: param1: Description of parameter 1 param2: Description of optional parameter 2 """ # Implementation here return "Result"Test the tool by running the server and testing with an MCP client.
Testing
Test the server by running it directly:
The server will start and wait for MCP protocol messages via stdin/stdout.
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
For issues related to:
MCP Server: Create an issue in this repository
Goodday API: Refer to Goodday API documentation
MCP Protocol: Refer to MCP documentation
Changelog
v1.1.0 (Current)
Enhanced Task Management: Added
get_task_details
andget_task_messages
for comprehensive task informationSprint Management: Added
get_goodday_sprint_tasks
andget_goodday_sprint_summary
for sprint trackingSmart Query Interface: Added
get_goodday_smart_query
for natural language project queriesSemantic Search: Added
search_goodday_tasks
with VectorDB integration for intelligent task searchDocument Management: Added
search_project_documents
andget_document_content
for document handlingImproved Error Handling: Enhanced error messages and status reporting
Advanced Filtering: Support for archived projects, closed tasks, and subfolder inclusion
v1.0.0
Initial release
Full project management capabilities
Task management with comments and status updates
User management
Comprehensive error handling
UV support with modern Python packaging
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
Goodday‑MCP is a lightweight Model Context Protocol (MCP) server designed to seamlessly integrate with the Goodday project management platform via its API v2. It enables querying of projects, tasks, and users—without altering any data—making it ideal for secure context-aware applications
Related MCP Servers
- -securityFlicense-qualityA specialized Model Context Protocol (MCP) server that integrates Google services (Gmail, Calendar, etc.) into your AI workflows. This server enables seamless access to Google services through MCP, allowing AI agents to interact with Gmail, Google Calendar, and other Google services.
Upstash MCP Serverofficial
AsecurityAlicenseAqualityModel Context Protocol (MCP) is a new, standardized protocol for managing context between large language models (LLMs) and external systems. In this repository, we provide an installer as well as an MCP Server for Upstash Developer API's.Last updated -47349MIT License- AsecurityFlicenseAqualityA Model Context Protocol (MCP) server that interacts with system APIs, allowing users to check connections, search employees, register breakfast, and update chemical information by shifts.
- AsecurityAlicenseAqualityA Model Context Protocol (MCP) server designed to easily dump your codebase context into Large Language Models (LLMs).Last updated -1182Apache 2.0