# Ticktickmcp

> 🤖 Manage TickTick tasks with Claude Desktop via MCP. Natural language task creation + Python CLI/API for automation.

- **Type:** MCP server
- **Install:** `agentstack add mcp-kbadinger-ticktickmcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kbadinger](https://agentstack.voostack.com/s/kbadinger)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kbadinger](https://github.com/kbadinger)
- **Source:** https://github.com/kbadinger/ticktickmcp
- **Website:** https://modelcontextprotocol.io

## Install

```sh
agentstack add mcp-kbadinger-ticktickmcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# TickTick API Client & MCP Server

[](https://modelcontextprotocol.io)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)

A Python client library for TickTick with **two ways to use it**:

1. **MCP Server** - Use TickTick with Claude Desktop through natural conversation
2. **Python CLI/Library** - Programmatic access for automation and scripting

## Choose Your Adventure

### 🤖 Want to use TickTick with Claude Desktop?
**→ [MCP Server Setup](MCP_README.md)**

Manage tasks through conversation:
```
You: "Add a high priority task to call mom tomorrow"
Claude: ✓ Created task: Call mom (Priority: High, Due: tomorrow)
```

### 💻 Want CLI tools or Python automation?
**→ Continue reading below**

Use command-line tools or build custom scripts:
```bash
python add_task.py "Buy groceries" --priority 5 --due today
```

---

## Overview

This project provides three approaches to interact with TickTick:

1. **MCP Server** (`ticktick_mcp_server.py`) - Model Context Protocol server for Claude Desktop
2. **REST API Client** (`ticktick_rest_api.py`) - Direct REST API implementation for automation
3. **OAuth Client** (`ticktick_setup.py`) - Uses the `ticktick-py` library (currently broken)

## Features

**MCP Server:**
- Natural language task creation and management
- Conversational interface through Claude Desktop
- Real-time task status and project overview
- Fuzzy search for tasks and projects

**Python Client:**
- Create and manage TickTick projects (lists)
- Create recurring tasks with RRULE syntax
- Set task priorities, due dates, and reminders
- OAuth2 authentication with token caching
- REST API implementation for advanced use cases
- Command-line tools for quick task addition

## Quick Start (5 Minutes)

### 1. Install Dependencies

```bash
pip install -r requirements.txt
```

### 2. Configure Credentials

Copy `.env.example` to `.env` and add your credentials:

```bash
cp .env.example .env
```

Edit `.env`:
```
TICKTICK_USERNAME=your-email@example.com
TICKTICK_PASSWORD=your-password
```

For REST API usage, also add:
```
TICKTICK_CLIENT_ID=your-client-id-here
TICKTICK_CLIENT_SECRET=your-client-secret-here
TICKTICK_REDIRECT_URI=http://127.0.0.1:8080
```

**Get API credentials:**
1. Go to https://developer.ticktick.com/manage
2. Click "+ App Name" and create an app
3. Set redirect URI to: `http://127.0.0.1:8080`
4. Copy your Client ID and Client Secret

### 3. Test Authentication

```bash
# Test OAuth client
python test_ticktick_auth.py

# Or test REST API
python ticktick_rest_api.py
```

## Usage Examples

### Quick Start: Add Individual Tasks (Recommended)

The easiest way to add tasks is using the `add_task.py` script:

```bash
# Simple task
python add_task.py "Buy groceries"

# Task with description
python add_task.py "Exercise" --content "30 min walk in the park"

# High priority task in a specific project
python add_task.py "Morning workout" --project Health --priority 5

# Task with due date
python add_task.py "Doctor appointment" --due "2025-11-20" --priority 5

# Task due today or tomorrow
python add_task.py "Call Nicole" --due today --priority 3
python add_task.py "Weekly check-in" --due tomorrow --project Marriage

# Full example with everything
python add_task.py "Weekly check-in" \
  --project Marriage \
  --content "Review the week together" \
  --priority 5 \
  --due tomorrow
```

**Adding long descriptions:**

```bash
# Multi-line description using heredoc
python add_task.py "Sunday Marriage Check-in" --project Marriage --priority 5 --content "$(cat <<'EOF'
6 Questions Framework:
1. Connection Score (1-10)
2. What Made Me Feel Loved
3. What Hurt or Frustrated Me
4. Body/Aging Struggle This Week
5. Intimacy Check
6. What I Need Next Week

Process:
- Both write answers (10 min)
- Share and listen (15 min)
- Connect physically (5 min)
EOF
)"
```

**Priority levels:**
- `5` = High (red)
- `3` = Medium (yellow)
- `1` = Low (blue)
- `0` = None (no color)

### REST API Client (For Full System Setup)

**⚠️ Important**: Use `ticktick_rest_api.py` instead of `ticktick_setup.py`. The OAuth client (ticktick-py library) is currently broken and re-authenticates on every run.

```bash
# Create entire Health & Marriage tracking system
python ticktick_rest_api.py --setup

# View current status
python ticktick_rest_api.py --status

# Test authentication
python ticktick_rest_api.py --auth
```

### Programmatic Usage (Advanced)

```python
from ticktick_rest_api import TickTickClient
import os

# Initialize client
client = TickTickClient(
    client_id=os.getenv('TICKTICK_CLIENT_ID'),
    client_secret=os.getenv('TICKTICK_CLIENT_SECRET'),
    redirect_uri='http://127.0.0.1:8080'
)

# Create a task
task = client.create_task(
    title="Important Task",
    content="Task description here",
    priority=5,
    dueDate="2024-12-31T23:59:59+0000",
    timeZone="America/Los_Angeles"
)

# Get all tasks
tasks = client.get_tasks()

# Get all projects
projects = client.get_projects()
```

## Project Structure

```
ticktick-api-client/
├── README.md                  # This file - Main documentation
├── MCP_README.md              # 🤖 MCP Server setup and usage
├── EXAMPLES.md                # 💬 Real-world MCP usage examples
├── CLAUDE.md                  # Guide for Claude Code
├── ticktick_mcp_server.py     # 🆕 MCP server implementation
├── add_task.py                # ⭐ Quick script to add individual tasks
├── ticktick_rest_api.py       # ✅ REST API client (WORKING)
├── ticktick_setup.py          # ❌ OAuth client (BROKEN - use REST API instead)
├── test_ticktick_auth.py      # Authentication testing
├── requirements.txt           # Python dependencies
├── pyproject.toml             # Package metadata
├── LICENSE                    # MIT License
├── .env.example               # Environment variables template
└── .gitignore                 # Git ignore rules
```

## Documentation

### MCP Server (Claude Desktop)
- **[MCP_README.md](MCP_README.md)** - 🤖 **MCP Server Setup** - Use TickTick with Claude Desktop
- **[EXAMPLES.md](EXAMPLES.md)** - 💬 **Usage Examples** - Real conversations with Claude

### Python CLI/Library
- **[GETTING-STARTED.md](GETTING-STARTED.md)** - ⭐ **START HERE** - Complete setup guide for new users
- **[ADDING-TASKS-CLI.md](ADDING-TASKS-CLI.md)** - ⭐ **Quick Reference** - Add tasks using `~/bin/tt` command
- **[TICKTICK-QUICKSTART.md](TICKTICK-QUICKSTART.md)** - Get started in 5 minutes
- **[TICKTICK-SETUP.md](TICKTICK-SETUP.md)** - Complete setup guide with examples
- **[CLAUDE.md](CLAUDE.md)** - Technical architecture and development guide

## API Reference

### Task Creation

```python
# Daily recurring task
repeat="RRULE:FREQ=DAILY;INTERVAL=1"

# Weekly on Sunday
repeat="RRULE:FREQ=WEEKLY;BYDAY=SU"

# Every 3 days
repeat="RRULE:FREQ=DAILY;INTERVAL=3"

# Weekdays only (Mon-Fri)
repeat="RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
```

### Priority Levels

- `5` = High (red)
- `3` = Medium (yellow)
- `1` = Low (blue)
- `0` = None (no color)

## Troubleshooting

### Authentication Failed

```bash
ValueError: TICKTICK_USERNAME and TICKTICK_PASSWORD must be set
```
**Fix:** Add credentials to `.env` file

### Tasks Not Appearing

- Check TickTick web/app to verify projects were created
- Run authentication test: `python test_ticktick_auth.py`
- Delete projects in TickTick and re-run setup

### Token Expired

Tokens are cached in `.ticktick-token.json` and `.token-oauth`. If authentication fails:

```bash
rm .ticktick-token.json .token-oauth
python test_ticktick_auth.py
```

## Use Cases

This library can be used for:

- Personal task management automation
- Habit tracking systems
- Project management integrations
- Team workflow automation
- Custom productivity tools
- Health and wellness tracking
- Recurring reminder systems

## Security

- Never commit `.env` file to version control
- Token files (`.ticktick-token.json`, `.token-oauth`) are auto-ignored
- OAuth tokens are cached locally for security
- Credentials are only used for initial authentication

## Dependencies

- `ticktick-py` - Official TickTick Python SDK
- `requests` - HTTP library for REST API
- `python-dotenv` - Environment variable management

## Contributing

This is a reference implementation. Feel free to:

- Fork and customize for your needs
- Add new features
- Improve error handling
- Extend REST API coverage

## License

MIT License - Use freely in your projects

## Links

- [TickTick Developer Portal](https://developer.ticktick.com)
- [TickTick API Documentation](https://developer.ticktick.com/api)
- [ticktick-py GitHub](https://github.com/lazeroffmichael/ticktick-py)

---

**Built for automation enthusiasts who want programmatic control over their TickTick workflows.**

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kbadinger](https://github.com/kbadinger)
- **Source:** [kbadinger/ticktickmcp](https://github.com/kbadinger/ticktickmcp)
- **License:** MIT
- **Homepage:** https://modelcontextprotocol.io

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kbadinger-ticktickmcp
- Seller: https://agentstack.voostack.com/s/kbadinger
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.