# Ticktick Mcp Server

> MCP server for TickTick integration

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

## Install

```sh
agentstack add mcp-rafliruslan-ticktick-mcp-server
```

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

## About

# TickTick MCP Server

A Model Context Protocol (MCP) server that provides integration with TickTick task management service.

## Features

- List tasks and projects with enhanced display (human-readable priorities)
- Create, update, and delete tasks
- Mark tasks as completed
- Get specific task details
- Timezone handling with manual D+1 adjustment for accurate due date calculations
- Get overdue tasks with configurable timezone offset
- Get today's tasks with proper timezone compensation
- OAuth and username/password authentication support
- Full TypeScript support with proper error handling

## Setup

1. Install dependencies:
```bash
npm install
```

2. Create environment configuration:
```bash
cp .env.example .env
```

3. Configure authentication in `.env`:

**Option A: OAuth (Recommended)**
```env
TICKTICK_ACCESS_TOKEN=your_oauth_access_token
TICKTICK_REFRESH_TOKEN=your_refresh_token
TICKTICK_CLIENT_ID=your_client_id
TICKTICK_CLIENT_SECRET=your_client_secret
```

**Option B: Username/Password**
```env
TICKTICK_USERNAME=your_ticktick_username
TICKTICK_PASSWORD=your_ticktick_password
```

For OAuth setup, see [OAUTH_SETUP.md](./OAUTH_SETUP.md) or use the helper:
```bash
node oauth-helper.js
```

4. Build the project:
```bash
npm run build
```

## Usage

### Development
```bash
npm run dev
```

### Production
```bash
npm start
```

## Available Tools

- `get_tasks` - Get all tasks or tasks from a specific project (with enhanced display)
- `get_overdue_tasks` - Get overdue tasks with timezone compensation (configurable offset, defaults to UTC+8 - adjust for your timezone)
- `get_todays_tasks` - Get tasks due today with D+1 timezone adjustment
- `get_projects` - Get all projects from TickTick
- `create_task` - Create a new task with priority, tags, due dates
- `update_task` - Update an existing task
- `delete_task` - Delete a task
- `complete_task` - Mark a task as completed
- `get_task` - Get a specific task by ID

### Timezone Handling

This server includes **manual timezone workarounds** to handle TickTick's timezone inconsistencies:

- **D+1 Adjustment**: Due dates are automatically adjusted by adding 1 day to compensate for timezone differences
- **Configurable Offset**: `get_overdue_tasks` accepts a `timezoneOffsetHours` parameter 
  - **Default**: 8 (UTC+8) - **Change this for your timezone!**
  - **Examples**: 
    - `timezoneOffsetHours: -5` for EST (UTC-5)
    - `timezoneOffsetHours: 0` for UTC
    - `timezoneOffsetHours: 9` for JST (UTC+9)
    - `timezoneOffsetHours: 1` for CET (UTC+1)
- **All-day vs Timed Tasks**: Different handling for all-day tasks vs specific time tasks
- **Enhanced Display**: Tasks include human-readable priority text (`None`, `Low`, `Medium`, `High`)

**Important**: The default timezone offset is set to UTC+8. Make sure to specify your correct timezone offset when calling `get_overdue_tasks` to get accurate results for your location.

## MCP Integration

### Claude Desktop (with Claude Desktop app)

Add this server to your MCP client configuration file:

**Location:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)

```json
{
  "mcpServers": {
    "ticktick": {
      "command": "node",
      "args": ["/path/to/ticktick-mcp-server/dist/index.js"],
      "env": {
        "TICKTICK_ACCESS_TOKEN": "your_oauth_token",
        "TICKTICK_REFRESH_TOKEN": "your_refresh_token",
        "TICKTICK_CLIENT_ID": "your_client_id",
        "TICKTICK_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

### Cursor IDE

Add this server to your Cursor MCP configuration:

**Location:** Create/edit `.cursorrules` or Cursor settings for MCP servers

```json
{
  "mcp": {
    "servers": {
      "ticktick": {
        "command": "node",
        "args": ["/path/to/ticktick-mcp-server/dist/index.js"],
        "env": {
          "TICKTICK_ACCESS_TOKEN": "your_oauth_token",
          "TICKTICK_REFRESH_TOKEN": "your_refresh_token", 
          "TICKTICK_CLIENT_ID": "your_client_id",
          "TICKTICK_CLIENT_SECRET": "your_client_secret"
        }
      }
    }
  }
}
```

### Alternative with Username/Password

```json
{
  "env": {
    "TICKTICK_USERNAME": "your_username",
    "TICKTICK_PASSWORD": "your_password"
  }
}
```

## License

MIT

## Source & license

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

- **Author:** [rafliruslan](https://github.com/rafliruslan)
- **Source:** [rafliruslan/ticktick-mcp-server](https://github.com/rafliruslan/ticktick-mcp-server)
- **License:** MIT

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-rafliruslan-ticktick-mcp-server
- Seller: https://agentstack.voostack.com/s/rafliruslan
- 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%.