# ticktick-md-mcp

A Python tool for importing and exporting TickTick notes and tasks to Markdown and JSON formats.

**Three ways to use:**
1. 🖥️ **Terminal CLI** - Interactive command-line interface
2. 🐍 **Python Library** - Import and use in your own code
3. 🤖 **MCP Server** - AI integration with Claude (via Model Context Protocol)

## Features

- OAuth 2.0 authentication with TickTick
- **Import tasks from Markdown files** with tags and project assignment
- Export tasks filtered by tag or entire projects
- Multiple export formats (Markdown, JSON)
- Automatic date extraction from task titles
- Extensible exporter architecture
- **🆕 MCP Server** - Expose functionality to Claude AI via Model Context Protocol

## Installation

### Prerequisites

- Python 3.11 or higher
- TickTick account
- TickTick OAuth app credentials ([Setup Guide](#ticktick-oauth-setup))

### Install Dependencies

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

# Or using uv (recommended)
uv pip install -r requirements.txt
```

## Quick Start

### 1. Set Up Environment Variables

Create a `.env` file in the project root:

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

Edit `.env` and add your TickTick OAuth credentials:

```env
TICKTICK_CLIENT_ID=your_client_id_here
TICKTICK_CLIENT_SECRET=your_client_secret_here
TICKTICK_REDIRECT_URI=http://localhost:8000/auth/ticktick/callback
TICKTICK_ACCESS_TOKEN=your_access_token_here
```

### 2. Get Access Token

Run the token helper to authenticate:

```bash
python -m src.utils.get_token
```

Follow the prompts to:
1. Visit the authorization URL
2. Authorize the app
3. Copy the authorization code from the redirect URL
4. The script will save your access token to `.env`

### 3. Run the CLI

```bash
python ticktick_cli.py
```

The interactive menu provides all functionality:
1. **Import tasks from Markdown** - Create tasks from markdown files with tags
2. **Export notes by tag** - Filter and export tasks by tag
3. **Export entire projects** - Export all tasks from a project
4. **List tags in a project** - See available tags
5. **Exit**

Choose your output format (Markdown or JSON) when exporting.

## Usage

The CLI provides a unified interface for all operations:

### Importing Tasks from Markdown

Run the CLI and select option 1:

```bash
python ticktick_cli.py
# Then select: 1. Import tasks from Markdown
```

You'll be prompted to:
1. Enter the markdown file path
2. Choose a default project (or leave empty for Inbox)
3. Preview (dry run) or import directly

#### Markdown Format

Tasks should be formatted as bullet lists with checkboxes:

```markdown
- [ ] Review pull request
  Tags: code-review, urgent
  Project: Work Tasks
  Check for performance issues and security

- [ ] Buy groceries
  Tags: shopping, personal
  Milk, bread, eggs

- [x] Completed task
  Tags: done
```

**Metadata Fields:**
- **Tags:** Comma-separated list of tags (e.g., `Tags: work, urgent`)
- **Project:** TickTick project/list name (e.g., `Project: Work Tasks`)
- **Description:** Multi-line task description (any non-metadata text after the title)

**Task States:**
- `- [ ]` - Unchecked task (will be imported)
- `- [x]` - Completed task (skipped during import)

### Exporting Tasks

Run the CLI and select option 2 or 3:

```bash
python ticktick_cli.py
# Then select:
# 2. Export notes by tag
# 3. Export entire project
```

**Export options:**
- Choose between Markdown or JSON format
- Specify output filename

### Programmatic Usage

If you need to use the functionality in your own Python scripts:

```python
from src.exporters.notes_exporter import NotesManager, MarkdownExporter, JSONExporter
from src.importers.task_importer import TaskImporter

# Initialize
manager = NotesManager()

# Export by tag (Markdown)
manager.export_by_tag(
    tag_name="journal",
    output_file="journal.md",
    project_name="On My Mind"
)

# Export by tag (JSON)
manager.export_by_tag(
    tag_name="work",
    output_file="work_notes.json",
    project_name="Work Tasks",
    exporter=JSONExporter()
)

# Export entire project
manager.export_project(
    project_name="Personal",
    output_file="personal_notes.md"
)

# List all projects
manager.list_projects()

# List tags in a project
manager.list_tags(project_name="On My Mind")
```

### API Usage

Use the TickTick API wrapper directly:

```python
from src.api.ticktick_api import TickTickAPI, TickTickOAuth
import os

# Initialize API
api = TickTickAPI(os.getenv('TICKTICK_ACCESS_TOKEN'))

# Get user info
user = api.get_user_info()

# Get all projects
projects = api.get_projects()

# Get project data with tasks
project_data = api.get_projects_data(project_id)

# Create a task
task = api.create_task(
    title="New Task",
    content="Task description",
    project_id="project_id_here",
    tags=["work", "urgent"]
)
```

## MCP Server - AI Integration

The MCP (Model Context Protocol) server allows Claude AI to directly interact with your TickTick account for importing and exporting tasks.

### What is MCP?

MCP is a protocol that lets AI assistants like Claude access external tools and data sources. With the TickTick MCP server, you can ask Claude to:
- "Export my work tasks to markdown"
- "Import these tasks to my Home project"
- "List all my TickTick projects"
- "Create a task in my Work project"

### Quick Start

1. **Install MCP dependency:**
   ```bash
   pip install mcp>=1.0.0
   ```

2. **The `.mcp.json` file is already configured** in the project root - no setup needed!

3. **Set your access token:**
   ```bash
   export TICKTICK_ACCESS_TOKEN=your_token_here
   ```

4. **Use with Claude Code:**
   - Open this project in Claude Code
   - The MCP server will be automatically detected
   - Ask Claude to interact with TickTick!

### Available MCP Tools

The server exposes these tools to Claude:

#### `list-projects`
List all your TickTick projects/lists.
```
Example: "Show me all my TickTick projects"
```

#### `list-tags`
List all tags in a specific project.
```
Parameters:
- project_name: Name of the project

Example: "What tags are in my Work Tasks project?"
```

#### `export-by-tag`
Export tasks filtered by a specific tag.
```
Parameters:
- tag_name: Tag to filter by
- project_name: Project to export from
- format: 'markdown' or 'json' (default: markdown)

Example: "Export all tasks tagged 'urgent' from Work Tasks"
```

#### `export-project`
Export all tasks from an entire project.
```
Parameters:
- project_name: Project to export
- format: 'markdown' or 'json' (default: markdown)

Example: "Export my Personal project as markdown"
```

#### `import-from-markdown`
Import tasks from markdown content into TickTick.
```
Parameters:
- markdown_content: Markdown formatted task list
- project_name: Target project (defaults to Inbox)
- dry_run: Preview without creating (default: true)

Example: "Import these tasks to my Work project:
- [ ] Review documentation
  Tags: work, urgent
- [ ] Schedule meeting
  Tags: work"
```

#### `create-task`
Create a single task in TickTick.
```
Parameters:
- title: Task title
- project_name: Project to add to (optional)
- content: Task description (optional)
- tags: List of tags (optional)

Example: "Create a task 'Buy groceries' with tags shopping and personal"
```

### Example Claude Conversations

**Export tasks:**
```
You: "Export all my work tasks tagged 'urgent' as markdown"
Claude: *uses export-by-tag tool*
Claude: "Here are your urgent work tasks: [markdown content]"
```

**Import tasks:**
```
You: "Here's a list of tasks, import them to my Home project:
- [ ] Fix leaky faucet
  Tags: home, maintenance
- [ ] Plant garden
  Tags: home, weekend"

Claude: *uses import-from-markdown tool with dry_run=false*
Claude: "I've imported 2 tasks to your Home project"
```

**List and organize:**
```
You: "What projects do I have in TickTick?"
Claude: *uses list-projects tool*
Claude: "You have 5 projects: Work Tasks, Personal, Home Tasks, Shopping, Ideas"
```

### MCP Configuration

The `.mcp.json` file in the project root is pre-configured:

```json
{
  "mcpServers": {
    "ticktick": {
      "command": "python3",
      "args": ["ticktick_mcp_server.py"]
    }
  }
}
```

Make sure `TICKTICK_ACCESS_TOKEN` is set in your environment or `.env` file.

**For Claude Desktop** (if you use it), add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "ticktick": {
      "command": "python3",
      "args": ["/absolute/path/to/pyTickTick/ticktick_mcp_server.py"],
      "env": {
        "TICKTICK_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Architecture

The MCP server reuses all existing code:
- Same API wrapper (`src/api/ticktick_api.py`)
- Same import logic (`src/importers/`)
- Same export logic (`src/exporters/`)

**No duplication** - the MCP server is a thin wrapper that exposes existing functionality to Claude via the Model Context Protocol.

### Troubleshooting MCP

**"Server not detected":**
- Ensure `.mcp.json` exists in project root
- Check that `TICKTICK_ACCESS_TOKEN` is set in environment
- Restart Claude Code

**"Authentication failed":**
- Run `python -m src.utils.get_token` to get a fresh token
- Update `.env` file with new token
- Set environment variable: `export TICKTICK_ACCESS_TOKEN=token`

**"Import not working":**
- Set `dry_run=False` in the import command
- Default is `dry_run=True` for safety (preview mode)

## Export Formats

### Markdown

Exports tasks as a formatted Markdown document:

```markdown
# Journal Notes

Exported on January 03, 2026 at 07:31 PM

Total notes: 7

---

## 2025-12-31 My Note Title

**Date:** December 31, 2025

Note content here...

---
```

**Features:**
- Tasks sorted by date (most recent first)
- Dates extracted from task titles (format: `YYYY-MM-DD`)
- Fallback to API dates if available
- Metadata header with export info

### JSON

Exports tasks as structured JSON:

```json
{
  "metadata": {
    "exported_at": "2026-01-03T19:31:00.123456",
    "total_tasks": 7,
    "tag_name": "journal",
    "project_name": "On My Mind"
  },
  "tasks": [
    {
      "id": "...",
      "title": "2025-12-31 My Note",
      "content": "Note content...",
      "tags": ["journal"],
      ...
    }
  ]
}
```

## Date Handling

The exporter intelligently handles dates:

1. **From Title** - Extracts dates from titles like `2025-12-31 Task Name`
   - Supports optional leading whitespace
   - Format: `YYYY-MM-DD` at the start of the title
   - Displays as: "December 31, 2025"

2. **From API** - Falls back to `modifiedTime` or `createdTime` if available
   - Note: TickTick's Open API may not return these fields for notes

3. **No Date** - Shows "No date" if neither source is available

## Utilities

### Get Token Helper

Quickly get a new OAuth access token:

```bash
python -m src.utils.get_token
```

### Debug Tags

Inspect task structure and find tags:

```bash
python -m src.utils.debug_tags
```

Shows:
- All projects in your account
- Sample task structures
- Tasks containing specific keywords
- Available tags

## Project Structure

```
pyTickTick/
├── 🚀 ticktick_cli.py        # Main CLI - Interactive terminal interface
├── 🤖 ticktick_mcp_server.py # MCP Server - AI integration with Claude
│
├── src/                      # Source code (organized by function)
│   ├── api/
│   │   └── ticktick_api.py   # TickTick API wrapper (OAuth + API client)
│   │
│   ├── exporters/
│   │   └── notes_exporter.py # Export tasks to Markdown/JSON
│   │
│   ├── importers/
│   │   ├── task_importer.py  # Import tasks from Markdown
│   │   └── markdown_parser.py# Parse markdown task format
│   │
│   └── utils/
│       ├── get_token.py      # OAuth token helper
│       └── debug_tags.py     # Task structure debugger
│
├── tests/                    # Comprehensive test suite
│   ├── conftest.py           # Pytest fixtures and configuration
│   ├── test_markdown_parser.py
│   ├── test_task_importer.py
│   ├── test_notes_exporter.py
│   └── test_ticktick_api.py
│
├── 📝 Config:
│   ├── .env.example          # Template for credentials (copy to .env)
│   ├── .mcp.json             # MCP server configuration for Claude
│   ├── requirements.txt      # Python dependencies
│   ├── pyproject.toml        # Project metadata
│   └── pytest.ini            # Pytest configuration
│
├── LICENSE                   # MIT License
└── README.md                 # This file
```

**Three Ways to Use:**
1. **Terminal CLI**: Run `python ticktick_cli.py` for interactive interface
2. **Python Library**: Import and use `src/` modules in your own code
3. **MCP with Claude**: Open project in Claude Code - MCP auto-detected!

**Getting Started:**
1. Run `python -m src.utils.get_token` once to authenticate
2. **CLI**: Run `python ticktick_cli.py` for all import/export operations
3. **MCP**: Open project in Claude Code and ask Claude to interact with TickTick!
4. (Optional) Run `python -m src.utils.debug_tags` to inspect task structures

## TickTick OAuth Setup

### 1. Create a TickTick Developer App

1. Go to [TickTick Developer Portal](https://developer.ticktick.com/)
2. Sign in with your TickTick account
3. Create a new app
4. Set the **Redirect URI** to: `http://localhost:8000/auth/ticktick/callback`
5. Copy your **Client ID** and **Client Secret**

### 2. Configure Environment

Add your credentials to `.env`:

```env
TICKTICK_CLIENT_ID=your_client_id_from_developer_portal
TICKTICK_CLIENT_SECRET=your_client_secret_from_developer_portal
TICKTICK_REDIRECT_URI=http://localhost:8000/auth/ticktick/callback
```

### 3. Get Access Token

Run `python -m src.utils.get_token` and follow the prompts.

## Troubleshooting

### "No access token found"

Run `python -m src.utils.get_token` to authenticate and get a new token.

### "Failed to fetch projects"

- Verify your access token is valid
- Check that your OAuth app has the correct scopes: `tasks:read tasks:write`
- Try getting a new token with `python -m src.utils.get_token`

### "No date" showing for all tasks

- The TickTick Open API doesn't return `createdTime`/`modifiedTime` for notes
- Add dates to your task titles in format `YYYY-MM-DD Task Name`
- The exporter will automatically extract and format these dates

### Import errors

Make sure all dependencies are installed:

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

## Development

### Testing

The project includes a comprehensive test suite using pytest.

#### Running Tests

```bash
# Install test dependencies
pip install -r requirements.txt

# Run all tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_markdown_parser.py

# Run tests with specific marker
pytest -m unit        # Run only unit tests
pytest -m integration # Run only integration tests
pytest -m api         # Run only API tests

# Run with verbose output
pytest -v
```

#### Test Structure

- **tests/conftest.py** - Shared fixtures and test configuration
- **tests/test_markdown_parser.py** - Tests for markdown parsing (40+ tests)
- **tests/test_task_importer.py** - Tests for task import functionality
- **tests/test_notes_exporter.py** - Tests for export functionality
- **tests/test_ticktick_api.py** - Tests for API wrapper

#### Test Coverage

The test suite covers:
- Markdown parsing with various formats
- Task import with dry-run and actual creation
- Export to Markdown and JSON formats
- API wrapper with mocked responses
- Edge cases and error handling
- Project and tag filtering

#### Writing New Tests

```python
# tests/test_example.py
import pytest

@pytest.mark.unit
def test_example(sample_markdown_content):
    """Test description"""
    # Your test code here
    assert True
```

Available fixtures:
- `sample_markdown_content` - Sample markdown for testing
- `mock_ticktick_api` - Mocked API instance
- `mock_env_token` - Mocked environment token
- `sample_tasks` - Sample task data

### File Responsibilities

- **src/api/ticktick_api.py** - Pure API wrapper, no business logic
- **src/exporters/notes_exporter.py** - Export logic and functionality
- **src/importers/task_importer.py** - Import logic and functionality
- **src/utils/get_token.py** - Simple OAuth flow helper
- **src/utils/debug_tags.py** - Debugging and inspection utility
- **ticktick_cli.py** - Main unified CLI interface

### Adding New Export Formats

Extend the `BaseExporter` class:

```python
from src.exporters.notes_exporter import BaseExporter

class CSVExporter(BaseExporter):
    def export(self, tasks, output_file, metadata):
        # Your CSV export logic here
        pass
```

Then use it:

```python
manager.export_by_tag(
    tag_name="notes",
    output_file="notes.csv",
    exporter=CSVExporter()
)
```

## Requirements

- python-dotenv >= 1.1.1
- requests >= 2.26.0

See `requirements.txt` for complete list.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## Roadmap

Future ideas under consideration:
- Full CLI interface with Click
- Additional export formats (CSV, HTML, PDF)
- Task management features (update, delete, complete)
- Configuration system
- Package distribution on PyPI

## Support

For issues or questions:
1. Check the [Troubleshooting](#troubleshooting) section
2. Review the [TickTick API Documentation](https://developer.ticktick.com/)
3. Open an issue (once repository is public)