[](https://fastmcp.me/MCP/Details/1371/goodday)
[](https://fastmcp.me/MCP/Details/1371/goodday)
[](https://fastmcp.me/MCP/Details/1371/goodday)
[](https://fastmcp.me/MCP/Details/1371/goodday)
[](https://fastmcp.me/MCP/Details/1371/goodday)
[](https://fastmcp.me/MCP/Details/1371/goodday)
# 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
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)
### 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)
```bash
pip install goodday-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):
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2. **Clone and set up the project**:
```bash
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
```bash
git clone https://github.com/cdmx1/goodday-mcp.git
cd goodday-mcp
pip install -e .
```
### Configuration
1. **Set up environment variables**:
Create a `.env` file in your project root or export the variable:
```bash
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
## Usage
### Running the Server Standalone
If installed from PyPI:
```bash
goodday-mcp
```
If running from source with UV:
```bash
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**:
**Option A: If installed from PyPI:**
```json
{
"mcpServers": {
"goodday": {
"command": "goodday-mcp",
"env": {
"GOODDAY_API_TOKEN": "your_goodday_api_token_here"
}
}
}
}
```
**Option B: If running from source:**
```json
{
"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.
### 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](https://modelcontextprotocol.io/) for client-specific integration instructions.
## API Reference
### Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `GOODDAY_API_TOKEN` | Your Goodday API token | Yes |
### Tool Examples
#### Get Projects
```python
# Get all active projects
get_projects()
# Get archived projects
get_projects(archived=True)
# Get only root-level projects
get_projects(root_only=True)
```
#### Create a Task
```python
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",
deadline="2025-06-30",
priority=5
)
```
#### Update Task Status
```python
update_task_status(
task_id="task_123",
user_id="user_456",
status_id="status_completed",
message="Task completed successfully"
)
```
## 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
```
goodday-mcp/
├── goodday_mcp/ # Main package directory
│ ├── __init__.py # Package initialization
│ └── main.py # Main MCP server implementation
├── pyproject.toml # Project configuration and dependencies
├── README.md # This file
├── LICENSE # MIT license
├── uv.lock # Dependency lock file
└── .env # Environment variables (create this)
```
### Adding New Tools
To add new tools to the server:
1. **Add the tool function** in `goodday_mcp/main.py` using the `@mcp.tool()` decorator:
```python
@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"
```
2. **Test the tool** by running the server and testing with an MCP client.
### Testing
Test the server by running it directly:
```bash
# If installed from PyPI
goodday-mcp
# If running from source
uv run goodday-mcp
```
The server will start and wait for MCP protocol messages via stdin/stdout.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. 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](https://www.goodday.work/developers/api-v2)
- **MCP Protocol**: Refer to [MCP documentation](https://modelcontextprotocol.io/)
## Changelog
### v1.1.0 (Current)
- **Enhanced Task Management**: Added `get_task_details` and `get_task_messages` for comprehensive task information
- **Sprint Management**: Added `get_goodday_sprint_tasks` and `get_goodday_sprint_summary` for sprint tracking
- **Smart Query Interface**: Added `get_goodday_smart_query` for natural language project queries
- **Semantic Search**: Added `search_goodday_tasks` with VectorDB integration for intelligent task search
- **Document Management**: Added `search_project_documents` and `get_document_content` for document handling
- **Improved 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
Raw data
{
"_id": null,
"home_page": null,
"name": "goodday-mcp-fastmcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, goodday, mcp, model-context-protocol, project-management, server",
"author": null,
"author_email": "Roney <roney@goodday-mcp.dev>",
"download_url": "https://files.pythonhosted.org/packages/20/e5/71066380a7a36c161124fa8a2aabd3b07e1344decd23d86513b0c5d1011c/goodday_mcp_fastmcp-1.1.1.tar.gz",
"platform": null,
"description": "[](https://fastmcp.me/MCP/Details/1371/goodday)\n[](https://fastmcp.me/MCP/Details/1371/goodday)\n[](https://fastmcp.me/MCP/Details/1371/goodday)\n[](https://fastmcp.me/MCP/Details/1371/goodday)\n[](https://fastmcp.me/MCP/Details/1371/goodday)\n[](https://fastmcp.me/MCP/Details/1371/goodday)\n\n# Goodday MCP Server\n\nA 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.\n\n## Features\n\n### Project Management\n- **get_projects**: Retrieve list of projects (with options for archived and root-only filtering)\n- **get_project**: Get detailed information about a specific project\n- **create_project**: Create new projects with customizable templates and settings\n- **get_project_users**: Get users associated with a specific project\n\n### Task Management\n- **get_project_tasks**: Retrieve tasks from specific projects (with options for closed tasks and subfolders)\n- **get_user_assigned_tasks**: Get tasks assigned to a specific user\n- **get_user_action_required_tasks**: Get action-required tasks for a user\n- **get_task**: Get detailed information about a specific task\n- **get_task_details**: Get comprehensive task details including subtasks, custom fields, and full metadata\n- **get_task_messages**: Retrieve all messages/comments for a specific task\n- **create_task**: Create new tasks with full customization (subtasks, assignments, dates, priorities)\n- **update_task_status**: Update task status with optional comments\n- **add_task_comment**: Add comments to tasks\n\n### Sprint Management\n- **get_goodday_sprint_tasks**: Get tasks from specific sprints by project name and sprint name/number\n- **get_goodday_sprint_summary**: Generate comprehensive sprint summaries with task details, status distribution, and key metrics\n\n### User Management\n- **get_users**: Retrieve list of organization users\n- **get_user**: Get detailed information about a specific user\n\n### Smart Query & Search\n- **get_goodday_smart_query**: Natural language interface for common project management queries\n- **search_goodday_tasks**: Semantic search across tasks using VectorDB backend\n- **search_project_documents**: Search for documents within specific projects\n- **get_document_content**: Retrieve full content of specific documents\n\n## OpenWebUI Integration\n\nThis package also includes an OpenWebUI tool that provides a complete interface for Goodday project management directly in chat interfaces. The OpenWebUI tool includes:\n\n### Features\n- **Project Management**: Get projects, project tasks, and project details\n- **Sprint Management**: Get tasks from specific sprints by name/number, comprehensive sprint summaries\n- **User Management**: Get tasks assigned to specific users, user details\n- **Task Details**: Get comprehensive task information including subtasks, custom fields, and metadata\n- **Task Messages**: Retrieve all messages and comments for tasks\n- **Smart Query**: Natural language interface for common project management requests\n- **Semantic Search**: Search across tasks using VectorDB backend with embeddings\n- **Document Management**: Search project documents and retrieve document content\n- **Advanced Filtering**: Support for archived projects, closed tasks, subfolders, and more\n\n### Setup\n1. Copy `openwebui/goodday_openwebui_complete_tool.py` to your OpenWebUI tools directory\n2. Configure the valves with your API credentials:\n - `api_key`: Your Goodday API token\n - `search_url`: Your VectorDB search endpoint (optional)\n - `bearer_token`: Bearer token for search API (optional)\n\n### Vector Database Setup (Optional)\nFor semantic search functionality, you can set up a vector database using the provided n8n workflow (`openwebui/n8n-workflow-goodday-vectordb.json`). This workflow:\n- Fetches all Goodday projects and tasks\n- Extracts task messages and content\n- Creates embeddings using Ollama\n- Stores in Qdrant vector database\n- Provides search API endpoint\n\nSee `openwebui/OPENWEBUI_TOOL_README.md` for detailed usage instructions.\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install goodday-mcp\n```\n\n### From Source\n\n#### Prerequisites\n- Python 3.10 or higher\n- UV package manager (recommended) or pip\n- Goodday API token\n\n#### Setup with UV\n\n1. **Install UV** (if not already installed):\n ```bash\n curl -LsSf https://astral.sh/uv/install.sh | sh\n ```\n\n2. **Clone and set up the project**:\n ```bash\n git clone https://github.com/cdmx1/goodday-mcp.git\n cd goodday-mcp\n \n # Create virtual environment and install dependencies\n uv venv\n source .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n uv sync\n ```\n\n#### Setup with pip\n\n```bash\ngit clone https://github.com/cdmx1/goodday-mcp.git\ncd goodday-mcp\npip install -e .\n```\n\n### Configuration\n\n1. **Set up environment variables**:\n Create a `.env` file in your project root or export the variable:\n ```bash\n export GOODDAY_API_TOKEN=your_goodday_api_token_here\n ```\n\n To get your Goodday API token:\n - Go to your Goodday organization\n - Navigate to Settings \u2192 API\n - Click the generate button to create a new token\n\n## Usage\n\n### Running the Server Standalone\n\nIf installed from PyPI:\n```bash\ngoodday-mcp\n```\n\nIf running from source with UV:\n```bash\nuv run goodday-mcp\n```\n\n### Using with Claude Desktop\n\n1. **Configure Claude Desktop** by editing your configuration file:\n - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. **Add the server configuration**:\n\n **Option A: If installed from PyPI:**\n ```json\n {\n \"mcpServers\": {\n \"goodday\": {\n \"command\": \"goodday-mcp\",\n \"env\": {\n \"GOODDAY_API_TOKEN\": \"your_goodday_api_token_here\"\n }\n }\n }\n }\n ```\n\n **Option B: If running from source:**\n ```json\n {\n \"mcpServers\": {\n \"goodday\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"goodday-mcp\"],\n \"env\": {\n \"GOODDAY_API_TOKEN\": \"your_goodday_api_token_here\"\n }\n }\n }\n }\n ```\n\n3. **Restart Claude Desktop** to load the new server.\n\n### Using with Other MCP Clients\n\nThe server communicates via stdio transport and can be integrated with any MCP-compatible client. Refer to the [MCP documentation](https://modelcontextprotocol.io/) for client-specific integration instructions.\n\n## API Reference\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `GOODDAY_API_TOKEN` | Your Goodday API token | Yes |\n\n### Tool Examples\n\n#### Get Projects\n```python\n# Get all active projects\nget_projects()\n\n# Get archived projects\nget_projects(archived=True)\n\n# Get only root-level projects\nget_projects(root_only=True)\n```\n\n#### Create a Task\n```python\ncreate_task(\n project_id=\"project_123\",\n title=\"Implement new feature\",\n from_user_id=\"user_456\",\n message=\"Detailed description of the task\",\n to_user_id=\"user_789\",\n deadline=\"2025-06-30\",\n priority=5\n)\n```\n\n#### Update Task Status\n```python\nupdate_task_status(\n task_id=\"task_123\",\n user_id=\"user_456\",\n status_id=\"status_completed\",\n message=\"Task completed successfully\"\n)\n```\n\n## Data Formats\n\n### Date Format\nAll dates should be provided in `YYYY-MM-DD` format (e.g., `2025-06-16`).\n\n### Priority Levels\n- 1-10: Normal priority levels\n- 50: Blocker\n- 100: Emergency\n\n### Project Colors\nProject colors are specified as integers from 1-24, corresponding to Goodday's color palette.\n\n## Error Handling\n\nThe server includes comprehensive error handling:\n- **Authentication errors**: When API token is missing or invalid\n- **Network errors**: When Goodday API is unreachable\n- **Validation errors**: When required parameters are missing\n- **Permission errors**: When user lacks permissions for requested operations\n\nAll errors are returned as descriptive strings to help with troubleshooting.\n\n## Development\n\n### Project Structure\n```\ngoodday-mcp/\n\u251c\u2500\u2500 goodday_mcp/ # Main package directory\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u2514\u2500\u2500 main.py # Main MCP server implementation\n\u251c\u2500\u2500 pyproject.toml # Project configuration and dependencies\n\u251c\u2500\u2500 README.md # This file\n\u251c\u2500\u2500 LICENSE # MIT license\n\u251c\u2500\u2500 uv.lock # Dependency lock file\n\u2514\u2500\u2500 .env # Environment variables (create this)\n```\n\n### Adding New Tools\n\nTo add new tools to the server:\n\n1. **Add the tool function** in `goodday_mcp/main.py` using the `@mcp.tool()` decorator:\n ```python\n @mcp.tool()\n async def your_new_tool(param1: str, param2: Optional[int] = None) -> str:\n \"\"\"Description of what the tool does.\n \n Args:\n param1: Description of parameter 1\n param2: Description of optional parameter 2\n \"\"\"\n # Implementation here\n return \"Result\"\n ```\n\n2. **Test the tool** by running the server and testing with an MCP client.\n\n### Testing\n\nTest the server by running it directly:\n```bash\n# If installed from PyPI\ngoodday-mcp\n\n# If running from source\nuv run goodday-mcp\n```\n\nThe server will start and wait for MCP protocol messages via stdin/stdout.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nFor issues related to:\n- **MCP Server**: Create an issue in this repository\n- **Goodday API**: Refer to [Goodday API documentation](https://www.goodday.work/developers/api-v2)\n- **MCP Protocol**: Refer to [MCP documentation](https://modelcontextprotocol.io/)\n\n## Changelog\n\n### v1.1.0 (Current)\n- **Enhanced Task Management**: Added `get_task_details` and `get_task_messages` for comprehensive task information\n- **Sprint Management**: Added `get_goodday_sprint_tasks` and `get_goodday_sprint_summary` for sprint tracking\n- **Smart Query Interface**: Added `get_goodday_smart_query` for natural language project queries\n- **Semantic Search**: Added `search_goodday_tasks` with VectorDB integration for intelligent task search\n- **Document Management**: Added `search_project_documents` and `get_document_content` for document handling\n- **Improved Error Handling**: Enhanced error messages and status reporting\n- **Advanced Filtering**: Support for archived projects, closed tasks, and subfolder inclusion\n\n### v1.0.0\n- Initial release\n- Full project management capabilities\n- Task management with comments and status updates\n- User management\n- Comprehensive error handling\n- UV support with modern Python packaging",
"bugtrack_url": null,
"license": null,
"summary": "Model Context Protocol server for Goodday project management platform",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/fastmcp-me/goodday-mcp#readme",
"Issues": "https://github.com/fastmcp-me/goodday-mcp/issues",
"Repository": "https://github.com/fastmcp-me/goodday-mcp.git"
},
"split_keywords": [
"api",
" goodday",
" mcp",
" model-context-protocol",
" project-management",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "961451691f7910ffc96c6f296bdf650a9a8c24cba0fc67f313b4452a4fcca597",
"md5": "932358f51a3a95760e087b4566f90d48",
"sha256": "df8841126205453019b300a8bcd914a25270cd4bad0d0ed3623ba276fbcc616b"
},
"downloads": -1,
"filename": "goodday_mcp_fastmcp-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "932358f51a3a95760e087b4566f90d48",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 16694,
"upload_time": "2025-11-07T21:52:41",
"upload_time_iso_8601": "2025-11-07T21:52:41.711237Z",
"url": "https://files.pythonhosted.org/packages/96/14/51691f7910ffc96c6f296bdf650a9a8c24cba0fc67f313b4452a4fcca597/goodday_mcp_fastmcp-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "20e571066380a7a36c161124fa8a2aabd3b07e1344decd23d86513b0c5d1011c",
"md5": "e4071d711668c8416e7682839a44091e",
"sha256": "32a4e8cf4f72b660bf0aead30f1dc1830980a6878603114722b0ad95d924c869"
},
"downloads": -1,
"filename": "goodday_mcp_fastmcp-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "e4071d711668c8416e7682839a44091e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 16898,
"upload_time": "2025-11-07T21:52:43",
"upload_time_iso_8601": "2025-11-07T21:52:43.056654Z",
"url": "https://files.pythonhosted.org/packages/20/e5/71066380a7a36c161124fa8a2aabd3b07e1344decd23d86513b0c5d1011c/goodday_mcp_fastmcp-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-07 21:52:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fastmcp-me",
"github_project": "goodday-mcp#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "goodday-mcp-fastmcp"
}
JSON
