| Name | donetick-mcp-server JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | MCP server for Donetick chores management with JWT authentication, Full API support, and 13 MCP tools |
| upload_time | 2025-11-04 03:36:21 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
mcp
donetick
chores
api
claude
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Donetick MCP Server
[](https://pypi.org/project/donetick-mcp-server/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/jason1365/donetick-mcp-server)
A production-ready Model Context Protocol (MCP) server for [Donetick](https://donetick.com) chores management. Enables Claude and other MCP-compatible AI assistants to interact with your Donetick instance through a secure, rate-limited API.
## Breaking Changes in v2.0.0
**Important**: Version 2.0.0 introduces breaking changes to authentication. If you're upgrading from v1.x, please read the [Migration Guide](MIGRATION.md).
**What Changed**:
- Authentication now uses JWT with username/password (instead of API tokens)
- API endpoints switched from eAPI to Full API
- 9 previously non-functional features now work (frequency metadata, rolling schedules, multiple assignees, assignment strategies, nagging notifications, pre-due notifications, private chores, points, sub-tasks)
- Premium membership no longer required for advanced features
**Quick Migration**:
1. Replace `DONETICK_API_TOKEN` environment variable with `DONETICK_USERNAME` and `DONETICK_PASSWORD`
2. Update your `.env` file or Claude Desktop configuration
3. Restart the server
See the [Migration Guide](MIGRATION.md) for detailed instructions.
## Features
- **13 MCP Tools**: Complete chore management (list, get, create, complete, delete), label organization (list, create, update, delete), circle member information, user management (list circle users, get user profile)
- **Full Chore Configuration**: All 26+ fields now working including frequency metadata, rolling schedules, multiple assignees, assignment strategies, notifications, labels, priority, points, sub-tasks, and more
- **JWT Authentication**: Automatic token management with transparent refresh
- **Smart Caching**: Intelligent caching for get_chore operations (60s TTL by default)
- **Rate Limiting**: Token bucket algorithm prevents API overload
- **Retry Logic**: Exponential backoff with jitter for resilient operations
- **Async/Await**: Non-blocking operations using httpx
- **Input Validation**: Pydantic field validators with sanitization
- **Security Hardened**: HTTPS enforcement, sanitized logging, secure error messages, JWT token security
- **Docker Support**: Containerized deployment with security best practices
- **Comprehensive Testing**: Unit and integration tests with pytest
- **Type Safety**: Pydantic models for request/response validation
## Quick Start
**Easiest installation (Claude Code CLI):**
```bash
claude mcp add donetick uvx donetick-mcp-server@latest
```
Then configure your Donetick credentials when prompted.
**Or install manually with uvx:**
```bash
# Install uv (one-time setup)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Add to Claude Desktop config
# ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"donetick": {
"command": "uvx",
"args": ["--refresh", "donetick-mcp-server"],
"env": {
"DONETICK_BASE_URL": "https://your-instance.com",
"DONETICK_USERNAME": "your_username",
"DONETICK_PASSWORD": "your_password"
}
}
}
}
```
**Benefits:**
- ✅ No installation required - runs directly from PyPI
- ✅ Auto-updates with `--refresh` flag
- ✅ Isolated environment - no conflicts
- ✅ Works on Windows, macOS, Linux
## Requirements
- Donetick instance (self-hosted or cloud)
- Donetick account credentials (username and password)
- **For uvx method:** `uv` installed (see Quick Start)
- **For other methods:** Python 3.11 or higher
## Installation
### Option 1: uvx (Recommended - No Installation Required)
See [Quick Start](#quick-start) above.
The `--refresh` flag ensures you always get the latest version when Claude Desktop restarts.
### Option 2: Docker
1. **Clone the repository**:
```bash
git clone https://github.com/jason1365/donetick-mcp-server.git
cd donetick-mcp-server
```
2. **Create `.env` file**:
```bash
cp .env.example .env
# Edit .env with your configuration
```
3. **Configure environment variables**:
```env
DONETICK_BASE_URL=https://your-instance.com
DONETICK_USERNAME=your_username
DONETICK_PASSWORD=your_password
LOG_LEVEL=INFO
```
4. **Build and run**:
```bash
docker-compose build
docker-compose up -d
```
### Option 3: pip install (For System Integration)
If you want to install globally or in a virtual environment:
```bash
# Install from PyPI
pip install donetick-mcp-server
# Or install for development
git clone https://github.com/jason1365/donetick-mcp-server.git
cd donetick-mcp-server
pip install -e .
# Run the server
donetick-mcp-server
# Or: python -m donetick_mcp.server
```
Then configure Claude Desktop to use the installed command:
```json
{
"mcpServers": {
"donetick": {
"command": "donetick-mcp-server",
"env": {
"DONETICK_BASE_URL": "https://your-instance.com",
"DONETICK_USERNAME": "your_username",
"DONETICK_PASSWORD": "your_password"
}
}
}
}
```
## Authentication
v2.0.0 uses JWT-based authentication with your Donetick credentials.
**What You Need**:
- Your Donetick username (same as web login)
- Your Donetick password (same as web login)
**How It Works**:
1. Server logs in with your credentials on startup
2. JWT token received and stored in memory
3. Token automatically refreshed before expiration
4. No manual token management required
**Security**:
- Credentials stored only in environment variables or `.env` file
- JWT tokens kept in memory only (never persisted to disk)
- Automatic token refresh prevents session expiration
- HTTPS required for all connections
## Claude Desktop Integration
**Easiest Method - Claude Code CLI:**
```bash
claude mcp add donetick uvx donetick-mcp-server@latest
```
**Or manually edit the 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`
### uvx Configuration (Recommended)
```json
{
"mcpServers": {
"donetick": {
"command": "uvx",
"args": ["--refresh", "donetick-mcp-server"],
"env": {
"DONETICK_BASE_URL": "https://your-instance.com",
"DONETICK_USERNAME": "your_username",
"DONETICK_PASSWORD": "your_password"
}
}
}
}
```
**Note:** The `--refresh` flag automatically updates to the latest version.
### Docker Configuration
```json
{
"mcpServers": {
"donetick": {
"command": "docker",
"args": [
"exec",
"-i",
"donetick-mcp-server",
"python",
"-m",
"donetick_mcp.server"
]
}
}
}
```
### pip install Configuration
```json
{
"mcpServers": {
"donetick": {
"command": "donetick-mcp-server",
"env": {
"DONETICK_BASE_URL": "https://your-instance.com",
"DONETICK_USERNAME": "your_username",
"DONETICK_PASSWORD": "your_password"
}
}
}
}
```
After updating the configuration, restart Claude Desktop.
## Available Tools
### 1. list_chores
List all chores with optional filtering.
**Parameters**:
- `filter_active` (boolean, optional): Filter by active status
- `assigned_to_user_id` (integer, optional): Filter by assigned user ID
**Example**:
```
List all active chores assigned to me
```
### 2. get_chore
Get details of a specific chore by ID.
**Parameters**:
- `chore_id` (integer, required): The chore ID
**Example**:
```
Show me details of chore 123
```
### 3. create_chore
Create a new chore with full configuration support.
**Basic Parameters**:
- `name` (string, required): Chore name (1-200 characters)
- `description` (string, optional): Chore description (max 5000 characters)
- `due_date` (string, optional): Due date in YYYY-MM-DD or RFC3339 format
- `created_by` (integer, optional): Creator user ID
**Recurrence/Frequency Parameters**:
- `frequency_type` (string, optional): How often chore repeats - "once", "daily", "weekly", "monthly", "yearly", "interval_based" (default: "once")
- `frequency` (integer, optional): Frequency multiplier, e.g., 1=weekly, 2=biweekly (default: 1)
- `frequency_metadata` (object, optional): Additional frequency config like `{"days": [1,3,5], "time": "09:00"}`
- `is_rolling` (boolean, optional): Rolling schedule (next due based on completion) vs fixed (default: false)
**User Assignment Parameters**:
- `assigned_to` (integer, optional): Primary assigned user ID
- `assignees` (array, optional): Multiple assignees as `[{"userId": 1}, {"userId": 2}]`
- `assign_strategy` (string, optional): Assignment strategy - "least_completed", "round_robin", "random" (default: "least_completed")
**Notification Parameters**:
- `notification` (boolean, optional): Enable notifications (default: false)
- `nagging` (boolean, optional): Enable nagging/reminder notifications (default: false)
- `predue` (boolean, optional): Enable pre-due date notifications (default: false)
**Organization Parameters**:
- `priority` (integer, optional): Priority level 1-5 (1=lowest, 5=highest)
- `labels` (array, optional): Label tags like `["cleaning", "outdoor"]`
**Status Parameters**:
- `is_active` (boolean, optional): Active status - inactive chores are hidden (default: true)
- `is_private` (boolean, optional): Private chore visible only to creator (default: false)
**Gamification Parameters**:
- `points` (integer, optional): Points awarded for completion
**Advanced Parameters**:
- `sub_tasks` (array, optional): Sub-tasks/checklist items
**Examples**:
```
Create a simple one-time chore:
Create a chore called "Take out trash" due on 2025-11-10
Create a recurring chore with notifications:
Create a weekly chore "Clean kitchen" every Monday at 9am with priority 4,
enable nagging notifications, and assign it to user 1
Create an advanced chore:
Create a chore "Grocery shopping" that repeats weekly on Mondays and Wednesdays,
assign to users 1 and 2 using round robin strategy, with priority 3,
labels "shopping" and "outdoor", and award 10 points
```
### 4. complete_chore
Mark a chore as complete.
**Parameters**:
- `chore_id` (integer, required): The chore ID
- `completed_by` (integer, optional): User ID who completed it
**Example**:
```
Mark chore 123 as complete
```
### 5. delete_chore
Delete a chore permanently. **Only the creator can delete**.
**Parameters**:
- `chore_id` (integer, required): The chore ID
**Example**:
```
Delete chore 123
```
### 6. get_circle_members
Get all members in your circle (household/team). Shows who you can assign chores to.
**Parameters**: None
**Returns**:
- User ID
- Username
- Display name
- Role (admin/member)
- Active status
- Points and redeemed points
**Example**:
```
Show me who's in my household
Who can I assign chores to?
List all circle members
```
## Configuration
### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DONETICK_BASE_URL` | Yes | - | Your Donetick instance URL (must use HTTPS) |
| `DONETICK_USERNAME` | Yes | - | Your Donetick username |
| `DONETICK_PASSWORD` | Yes | - | Your Donetick password |
| `LOG_LEVEL` | No | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |
| `RATE_LIMIT_PER_SECOND` | No | 10.0 | Requests per second limit |
| `RATE_LIMIT_BURST` | No | 10 | Maximum burst size |
### Rate Limiting
The server implements a token bucket rate limiter to prevent API overload:
- **Default**: 10 requests per second with burst capacity of 10
- **Conservative**: Starts conservative and can be increased based on your Donetick instance
- **Respects 429**: Automatically backs off when rate limited by the API
### Retry Logic
- **Exponential backoff** with jitter for transient failures
- **Maximum 3 retries** for most operations
- **Smart retry**: Only retries on 5xx errors and 429 (rate limit)
- **No retry on 4xx**: Client errors fail immediately (except 429)
## Development
### Running Tests
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run all tests
pytest
# Run with coverage
pytest --cov=donetick_mcp --cov-report=html
# Run specific test file
pytest tests/test_client.py
# Run with verbose output
pytest -v
```
### Project Structure
```
donetick-mcp-server/
├── src/donetick_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server implementation
│ ├── client.py # Donetick API client
│ ├── models.py # Pydantic data models
│ └── config.py # Configuration management
├── tests/
│ ├── test_client.py # API client tests
│ └── test_server.py # MCP server tests
├── tmp/ # Temporary files (gitignored)
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── README.md
```
**Note**: The `tmp/` directory is used for temporary test scripts and analysis files during development. It's gitignored and not included in releases.
## API Documentation
This server uses the Donetick Full API with JWT authentication. Official documentation:
- **API Docs**: https://docs.donetick.com/
- **GitHub**: https://github.com/donetick/donetick
### Important Notes
1. **Authentication**: Uses JWT Bearer tokens (automatically managed)
2. **Full Feature Support**: All 26+ chore creation fields now working
3. **Automatic Token Refresh**: JWT tokens refreshed transparently
4. **Circle Scoped**: All operations are scoped to your circle (household/team)
5. **No Premium Required**: Advanced features work with standard accounts
## Troubleshooting
### Common Issues
**"DONETICK_BASE_URL environment variable is required"**
- Make sure your `.env` file exists and is properly formatted
- For Docker: ensure environment variables are passed in docker-compose.yml
**"Rate limited, waiting..."**
- The server is respecting API rate limits
- Consider reducing `RATE_LIMIT_PER_SECOND` if this happens frequently
**"Connection refused" or timeout errors**
- Verify your Donetick instance URL is correct
- Check that your Donetick instance is accessible
- Ensure firewall rules allow outbound connections
**"401 Unauthorized" or "Invalid credentials"**
- Verify your username and password are correct
- Check that your account is not locked or disabled
- Ensure you can login to Donetick web interface with the same credentials
- Check for typos in environment variables
**Tools not showing in Claude**
- Restart Claude Desktop after configuration changes
- Check Claude Desktop logs for errors
- Verify the configuration file path is correct
### Debugging
Enable debug logging:
```bash
export LOG_LEVEL=DEBUG
```
Or in Docker:
```yaml
environment:
- LOG_LEVEL=DEBUG
```
View Docker logs:
```bash
docker-compose logs -f donetick-mcp
```
## Security
- **Credentials**: Never commit credentials to version control (use `.env` file)
- **JWT Tokens**: Stored in memory only, never persisted to disk
- **Automatic Token Refresh**: Prevents session expiration without user intervention
- **Docker Isolation**: Runs as non-root user in container
- **Resource Limits**: Memory and CPU limits prevent resource exhaustion
- **Input Validation**: Pydantic models validate all inputs
- **HTTPS Required**: Server enforces HTTPS for all Donetick connections
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## License
MIT License - see LICENSE file for details
## Acknowledgments
- [Donetick](https://donetick.com) - Open source chores management
- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification
- [Anthropic](https://anthropic.com) - MCP SDK and Claude
## Support
- **Issues**: https://github.com/jason1365/donetick-mcp-server/issues
- **Donetick Docs**: https://docs.donetick.com
- **MCP Docs**: https://modelcontextprotocol.io
---
Built with ❤️ for the Donetick and MCP communities
Raw data
{
"_id": null,
"home_page": null,
"name": "donetick-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "mcp, donetick, chores, api, claude",
"author": null,
"author_email": "Jason <jason1365@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/24/a8/ad60ce22ea5b292afbcd338dae7652db443589f8b78ff2af400025a99f71/donetick_mcp_server-0.3.0.tar.gz",
"platform": null,
"description": "# Donetick MCP Server\n\n[](https://pypi.org/project/donetick-mcp-server/)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/jason1365/donetick-mcp-server)\n\nA production-ready Model Context Protocol (MCP) server for [Donetick](https://donetick.com) chores management. Enables Claude and other MCP-compatible AI assistants to interact with your Donetick instance through a secure, rate-limited API.\n\n## Breaking Changes in v2.0.0\n\n**Important**: Version 2.0.0 introduces breaking changes to authentication. If you're upgrading from v1.x, please read the [Migration Guide](MIGRATION.md).\n\n**What Changed**:\n- Authentication now uses JWT with username/password (instead of API tokens)\n- API endpoints switched from eAPI to Full API\n- 9 previously non-functional features now work (frequency metadata, rolling schedules, multiple assignees, assignment strategies, nagging notifications, pre-due notifications, private chores, points, sub-tasks)\n- Premium membership no longer required for advanced features\n\n**Quick Migration**:\n1. Replace `DONETICK_API_TOKEN` environment variable with `DONETICK_USERNAME` and `DONETICK_PASSWORD`\n2. Update your `.env` file or Claude Desktop configuration\n3. Restart the server\n\nSee the [Migration Guide](MIGRATION.md) for detailed instructions.\n\n## Features\n\n- **13 MCP Tools**: Complete chore management (list, get, create, complete, delete), label organization (list, create, update, delete), circle member information, user management (list circle users, get user profile)\n- **Full Chore Configuration**: All 26+ fields now working including frequency metadata, rolling schedules, multiple assignees, assignment strategies, notifications, labels, priority, points, sub-tasks, and more\n- **JWT Authentication**: Automatic token management with transparent refresh\n- **Smart Caching**: Intelligent caching for get_chore operations (60s TTL by default)\n- **Rate Limiting**: Token bucket algorithm prevents API overload\n- **Retry Logic**: Exponential backoff with jitter for resilient operations\n- **Async/Await**: Non-blocking operations using httpx\n- **Input Validation**: Pydantic field validators with sanitization\n- **Security Hardened**: HTTPS enforcement, sanitized logging, secure error messages, JWT token security\n- **Docker Support**: Containerized deployment with security best practices\n- **Comprehensive Testing**: Unit and integration tests with pytest\n- **Type Safety**: Pydantic models for request/response validation\n\n## Quick Start\n\n**Easiest installation (Claude Code CLI):**\n\n```bash\nclaude mcp add donetick uvx donetick-mcp-server@latest\n```\n\nThen configure your Donetick credentials when prompted.\n\n**Or install manually with uvx:**\n\n```bash\n# Install uv (one-time setup)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Add to Claude Desktop config\n# ~/.config/Claude/claude_desktop_config.json\n{\n \"mcpServers\": {\n \"donetick\": {\n \"command\": \"uvx\",\n \"args\": [\"--refresh\", \"donetick-mcp-server\"],\n \"env\": {\n \"DONETICK_BASE_URL\": \"https://your-instance.com\",\n \"DONETICK_USERNAME\": \"your_username\",\n \"DONETICK_PASSWORD\": \"your_password\"\n }\n }\n }\n}\n```\n\n**Benefits:**\n- \u2705 No installation required - runs directly from PyPI\n- \u2705 Auto-updates with `--refresh` flag\n- \u2705 Isolated environment - no conflicts\n- \u2705 Works on Windows, macOS, Linux\n\n## Requirements\n\n- Donetick instance (self-hosted or cloud)\n- Donetick account credentials (username and password)\n- **For uvx method:** `uv` installed (see Quick Start)\n- **For other methods:** Python 3.11 or higher\n\n## Installation\n\n### Option 1: uvx (Recommended - No Installation Required)\n\nSee [Quick Start](#quick-start) above.\n\nThe `--refresh` flag ensures you always get the latest version when Claude Desktop restarts.\n\n### Option 2: Docker\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/jason1365/donetick-mcp-server.git\n cd donetick-mcp-server\n ```\n\n2. **Create `.env` file**:\n ```bash\n cp .env.example .env\n # Edit .env with your configuration\n ```\n\n3. **Configure environment variables**:\n ```env\n DONETICK_BASE_URL=https://your-instance.com\n DONETICK_USERNAME=your_username\n DONETICK_PASSWORD=your_password\n LOG_LEVEL=INFO\n ```\n\n4. **Build and run**:\n ```bash\n docker-compose build\n docker-compose up -d\n ```\n\n### Option 3: pip install (For System Integration)\n\nIf you want to install globally or in a virtual environment:\n\n```bash\n# Install from PyPI\npip install donetick-mcp-server\n\n# Or install for development\ngit clone https://github.com/jason1365/donetick-mcp-server.git\ncd donetick-mcp-server\npip install -e .\n\n# Run the server\ndonetick-mcp-server\n# Or: python -m donetick_mcp.server\n```\n\nThen configure Claude Desktop to use the installed command:\n\n```json\n{\n \"mcpServers\": {\n \"donetick\": {\n \"command\": \"donetick-mcp-server\",\n \"env\": {\n \"DONETICK_BASE_URL\": \"https://your-instance.com\",\n \"DONETICK_USERNAME\": \"your_username\",\n \"DONETICK_PASSWORD\": \"your_password\"\n }\n }\n }\n}\n```\n\n## Authentication\n\nv2.0.0 uses JWT-based authentication with your Donetick credentials.\n\n**What You Need**:\n- Your Donetick username (same as web login)\n- Your Donetick password (same as web login)\n\n**How It Works**:\n1. Server logs in with your credentials on startup\n2. JWT token received and stored in memory\n3. Token automatically refreshed before expiration\n4. No manual token management required\n\n**Security**:\n- Credentials stored only in environment variables or `.env` file\n- JWT tokens kept in memory only (never persisted to disk)\n- Automatic token refresh prevents session expiration\n- HTTPS required for all connections\n\n## Claude Desktop Integration\n\n**Easiest Method - Claude Code CLI:**\n\n```bash\nclaude mcp add donetick uvx donetick-mcp-server@latest\n```\n\n**Or manually edit the configuration file:**\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n**Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n### uvx Configuration (Recommended)\n\n```json\n{\n \"mcpServers\": {\n \"donetick\": {\n \"command\": \"uvx\",\n \"args\": [\"--refresh\", \"donetick-mcp-server\"],\n \"env\": {\n \"DONETICK_BASE_URL\": \"https://your-instance.com\",\n \"DONETICK_USERNAME\": \"your_username\",\n \"DONETICK_PASSWORD\": \"your_password\"\n }\n }\n }\n}\n```\n\n**Note:** The `--refresh` flag automatically updates to the latest version.\n\n### Docker Configuration\n\n```json\n{\n \"mcpServers\": {\n \"donetick\": {\n \"command\": \"docker\",\n \"args\": [\n \"exec\",\n \"-i\",\n \"donetick-mcp-server\",\n \"python\",\n \"-m\",\n \"donetick_mcp.server\"\n ]\n }\n }\n}\n```\n\n### pip install Configuration\n\n```json\n{\n \"mcpServers\": {\n \"donetick\": {\n \"command\": \"donetick-mcp-server\",\n \"env\": {\n \"DONETICK_BASE_URL\": \"https://your-instance.com\",\n \"DONETICK_USERNAME\": \"your_username\",\n \"DONETICK_PASSWORD\": \"your_password\"\n }\n }\n }\n}\n```\n\nAfter updating the configuration, restart Claude Desktop.\n\n## Available Tools\n\n### 1. list_chores\n\nList all chores with optional filtering.\n\n**Parameters**:\n- `filter_active` (boolean, optional): Filter by active status\n- `assigned_to_user_id` (integer, optional): Filter by assigned user ID\n\n**Example**:\n```\nList all active chores assigned to me\n```\n\n### 2. get_chore\n\nGet details of a specific chore by ID.\n\n**Parameters**:\n- `chore_id` (integer, required): The chore ID\n\n**Example**:\n```\nShow me details of chore 123\n```\n\n### 3. create_chore\n\nCreate a new chore with full configuration support.\n\n**Basic Parameters**:\n- `name` (string, required): Chore name (1-200 characters)\n- `description` (string, optional): Chore description (max 5000 characters)\n- `due_date` (string, optional): Due date in YYYY-MM-DD or RFC3339 format\n- `created_by` (integer, optional): Creator user ID\n\n**Recurrence/Frequency Parameters**:\n- `frequency_type` (string, optional): How often chore repeats - \"once\", \"daily\", \"weekly\", \"monthly\", \"yearly\", \"interval_based\" (default: \"once\")\n- `frequency` (integer, optional): Frequency multiplier, e.g., 1=weekly, 2=biweekly (default: 1)\n- `frequency_metadata` (object, optional): Additional frequency config like `{\"days\": [1,3,5], \"time\": \"09:00\"}`\n- `is_rolling` (boolean, optional): Rolling schedule (next due based on completion) vs fixed (default: false)\n\n**User Assignment Parameters**:\n- `assigned_to` (integer, optional): Primary assigned user ID\n- `assignees` (array, optional): Multiple assignees as `[{\"userId\": 1}, {\"userId\": 2}]`\n- `assign_strategy` (string, optional): Assignment strategy - \"least_completed\", \"round_robin\", \"random\" (default: \"least_completed\")\n\n**Notification Parameters**:\n- `notification` (boolean, optional): Enable notifications (default: false)\n- `nagging` (boolean, optional): Enable nagging/reminder notifications (default: false)\n- `predue` (boolean, optional): Enable pre-due date notifications (default: false)\n\n**Organization Parameters**:\n- `priority` (integer, optional): Priority level 1-5 (1=lowest, 5=highest)\n- `labels` (array, optional): Label tags like `[\"cleaning\", \"outdoor\"]`\n\n**Status Parameters**:\n- `is_active` (boolean, optional): Active status - inactive chores are hidden (default: true)\n- `is_private` (boolean, optional): Private chore visible only to creator (default: false)\n\n**Gamification Parameters**:\n- `points` (integer, optional): Points awarded for completion\n\n**Advanced Parameters**:\n- `sub_tasks` (array, optional): Sub-tasks/checklist items\n\n**Examples**:\n```\nCreate a simple one-time chore:\nCreate a chore called \"Take out trash\" due on 2025-11-10\n\nCreate a recurring chore with notifications:\nCreate a weekly chore \"Clean kitchen\" every Monday at 9am with priority 4,\nenable nagging notifications, and assign it to user 1\n\nCreate an advanced chore:\nCreate a chore \"Grocery shopping\" that repeats weekly on Mondays and Wednesdays,\nassign to users 1 and 2 using round robin strategy, with priority 3,\nlabels \"shopping\" and \"outdoor\", and award 10 points\n```\n\n### 4. complete_chore\n\nMark a chore as complete.\n\n**Parameters**:\n- `chore_id` (integer, required): The chore ID\n- `completed_by` (integer, optional): User ID who completed it\n\n**Example**:\n```\nMark chore 123 as complete\n```\n\n### 5. delete_chore\n\nDelete a chore permanently. **Only the creator can delete**.\n\n**Parameters**:\n- `chore_id` (integer, required): The chore ID\n\n**Example**:\n```\nDelete chore 123\n```\n\n### 6. get_circle_members\n\nGet all members in your circle (household/team). Shows who you can assign chores to.\n\n**Parameters**: None\n\n**Returns**:\n- User ID\n- Username\n- Display name\n- Role (admin/member)\n- Active status\n- Points and redeemed points\n\n**Example**:\n```\nShow me who's in my household\nWho can I assign chores to?\nList all circle members\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `DONETICK_BASE_URL` | Yes | - | Your Donetick instance URL (must use HTTPS) |\n| `DONETICK_USERNAME` | Yes | - | Your Donetick username |\n| `DONETICK_PASSWORD` | Yes | - | Your Donetick password |\n| `LOG_LEVEL` | No | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |\n| `RATE_LIMIT_PER_SECOND` | No | 10.0 | Requests per second limit |\n| `RATE_LIMIT_BURST` | No | 10 | Maximum burst size |\n\n### Rate Limiting\n\nThe server implements a token bucket rate limiter to prevent API overload:\n\n- **Default**: 10 requests per second with burst capacity of 10\n- **Conservative**: Starts conservative and can be increased based on your Donetick instance\n- **Respects 429**: Automatically backs off when rate limited by the API\n\n### Retry Logic\n\n- **Exponential backoff** with jitter for transient failures\n- **Maximum 3 retries** for most operations\n- **Smart retry**: Only retries on 5xx errors and 429 (rate limit)\n- **No retry on 4xx**: Client errors fail immediately (except 429)\n\n## Development\n\n### Running Tests\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=donetick_mcp --cov-report=html\n\n# Run specific test file\npytest tests/test_client.py\n\n# Run with verbose output\npytest -v\n```\n\n### Project Structure\n\n```\ndonetick-mcp-server/\n\u251c\u2500\u2500 src/donetick_mcp/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 server.py # MCP server implementation\n\u2502 \u251c\u2500\u2500 client.py # Donetick API client\n\u2502 \u251c\u2500\u2500 models.py # Pydantic data models\n\u2502 \u2514\u2500\u2500 config.py # Configuration management\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 test_client.py # API client tests\n\u2502 \u2514\u2500\u2500 test_server.py # MCP server tests\n\u251c\u2500\u2500 tmp/ # Temporary files (gitignored)\n\u251c\u2500\u2500 Dockerfile\n\u251c\u2500\u2500 docker-compose.yml\n\u251c\u2500\u2500 pyproject.toml\n\u2514\u2500\u2500 README.md\n```\n\n**Note**: The `tmp/` directory is used for temporary test scripts and analysis files during development. It's gitignored and not included in releases.\n\n## API Documentation\n\nThis server uses the Donetick Full API with JWT authentication. Official documentation:\n- **API Docs**: https://docs.donetick.com/\n- **GitHub**: https://github.com/donetick/donetick\n\n### Important Notes\n\n1. **Authentication**: Uses JWT Bearer tokens (automatically managed)\n2. **Full Feature Support**: All 26+ chore creation fields now working\n3. **Automatic Token Refresh**: JWT tokens refreshed transparently\n4. **Circle Scoped**: All operations are scoped to your circle (household/team)\n5. **No Premium Required**: Advanced features work with standard accounts\n\n## Troubleshooting\n\n### Common Issues\n\n**\"DONETICK_BASE_URL environment variable is required\"**\n- Make sure your `.env` file exists and is properly formatted\n- For Docker: ensure environment variables are passed in docker-compose.yml\n\n**\"Rate limited, waiting...\"**\n- The server is respecting API rate limits\n- Consider reducing `RATE_LIMIT_PER_SECOND` if this happens frequently\n\n**\"Connection refused\" or timeout errors**\n- Verify your Donetick instance URL is correct\n- Check that your Donetick instance is accessible\n- Ensure firewall rules allow outbound connections\n\n**\"401 Unauthorized\" or \"Invalid credentials\"**\n- Verify your username and password are correct\n- Check that your account is not locked or disabled\n- Ensure you can login to Donetick web interface with the same credentials\n- Check for typos in environment variables\n\n**Tools not showing in Claude**\n- Restart Claude Desktop after configuration changes\n- Check Claude Desktop logs for errors\n- Verify the configuration file path is correct\n\n### Debugging\n\nEnable debug logging:\n\n```bash\nexport LOG_LEVEL=DEBUG\n```\n\nOr in Docker:\n\n```yaml\nenvironment:\n - LOG_LEVEL=DEBUG\n```\n\nView Docker logs:\n\n```bash\ndocker-compose logs -f donetick-mcp\n```\n\n## Security\n\n- **Credentials**: Never commit credentials to version control (use `.env` file)\n- **JWT Tokens**: Stored in memory only, never persisted to disk\n- **Automatic Token Refresh**: Prevents session expiration without user intervention\n- **Docker Isolation**: Runs as non-root user in container\n- **Resource Limits**: Memory and CPU limits prevent resource exhaustion\n- **Input Validation**: Pydantic models validate all inputs\n- **HTTPS Required**: Server enforces HTTPS for all Donetick connections\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Acknowledgments\n\n- [Donetick](https://donetick.com) - Open source chores management\n- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification\n- [Anthropic](https://anthropic.com) - MCP SDK and Claude\n\n## Support\n\n- **Issues**: https://github.com/jason1365/donetick-mcp-server/issues\n- **Donetick Docs**: https://docs.donetick.com\n- **MCP Docs**: https://modelcontextprotocol.io\n\n---\n\nBuilt with \u2764\ufe0f for the Donetick and MCP communities\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Donetick chores management with JWT authentication, Full API support, and 13 MCP tools",
"version": "0.3.0",
"project_urls": {
"Changelog": "https://github.com/jason1365/donetick-mcp-server/releases",
"Documentation": "https://github.com/jason1365/donetick-mcp-server#readme",
"Homepage": "https://github.com/jason1365/donetick-mcp-server",
"Issues": "https://github.com/jason1365/donetick-mcp-server/issues",
"Repository": "https://github.com/jason1365/donetick-mcp-server"
},
"split_keywords": [
"mcp",
" donetick",
" chores",
" api",
" claude"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5ef91e8c23975e8238b2ffcff4908e5096299e1608998e030941ddce5dcc770a",
"md5": "c54a202f93d69b3d3b56527e009c2d89",
"sha256": "87d102209a19569ec60d440d999878833d0ee5fcdf4ed611c31a2f7954c0e2d4"
},
"downloads": -1,
"filename": "donetick_mcp_server-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c54a202f93d69b3d3b56527e009c2d89",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 30016,
"upload_time": "2025-11-04T03:36:20",
"upload_time_iso_8601": "2025-11-04T03:36:20.725682Z",
"url": "https://files.pythonhosted.org/packages/5e/f9/1e8c23975e8238b2ffcff4908e5096299e1608998e030941ddce5dcc770a/donetick_mcp_server-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "24a8ad60ce22ea5b292afbcd338dae7652db443589f8b78ff2af400025a99f71",
"md5": "290be5ef20d5e18b2052b0919856826e",
"sha256": "dbb49af9d9b4100144c4930b3de5ba5583d9cec2419edb3af5400325ca0e18b6"
},
"downloads": -1,
"filename": "donetick_mcp_server-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "290be5ef20d5e18b2052b0919856826e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 38267,
"upload_time": "2025-11-04T03:36:21",
"upload_time_iso_8601": "2025-11-04T03:36:21.970796Z",
"url": "https://files.pythonhosted.org/packages/24/a8/ad60ce22ea5b292afbcd338dae7652db443589f8b78ff2af400025a99f71/donetick_mcp_server-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-04 03:36:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jason1365",
"github_project": "donetick-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "donetick-mcp-server"
}
