Efficient TickTick

Part of the Efficient MCP series - TickTick task management optimized for LLMs with 70% lower token costs.

Unlike raw API access, this MCP server is designed specifically for AI assistants to understand and work with your tasks naturally. It handles timezone conversions, provides relative time contexts ("in 2 hours", "overdue by 3 days"), and offers semantic tools that make sense to LLMs.

Efficiency First: Reduce token costs by 70% compared to raw API usage through intelligent batching, pre-calculated states, and rich context in single calls.

Why?

Traditional task management APIs are built for human UIs. When an LLM uses them, it has to:

• Do complex timezone math
• Chain multiple API calls to get context
• Parse dates and figure out relative times
• Understand priority schemes

TickTick MCP solves this by providing:

• ✅ Rich time contexts - Every task includes ISO, relative, and local time formats
• ✅ Semantic tools - suggest_next_task() instead of generic CRUD
• ✅ Smart suggestions - AI-powered task prioritization based on deadlines and context
• ✅ Flexible input - Accepts "today", "tomorrow", "next week" instead of just ISO dates
• ✅ Complete context - One API call gives you everything (task + project + parent + time)

Features

• 🧠 LLM-first design - Optimized for AI assistant consumption
• ⏰ Intelligent time handling - Automatic timezone conversion and relative time formatting
• 🎯 Smart suggestions - AI-powered next task recommendations
• 🔍 Semantic search - Find tasks by keyword, project, or deadline
• 📊 Batch operations - Get complete context in a single call
• 🚀 Built with Bun - Fast, modern TypeScript runtime

Installation

Using npx/bunx (Recommended)

bunx @om-surushe/efficient-ticktick

Global Install

npm install -g @om-surushe/efficient-ticktick
# or
bun install -g @om-surushe/efficient-ticktick

From Source

git clone https://github.com/om-surushe/efficient-ticktick.git
cd efficient-ticktick
bun install
bun run build

Setup

1. Get Your TickTick API Token

1. Open TickTick app or web
2. Go to Settings → Open API
3. Copy your personal API token (starts with tp_...)

2. Configure MCP Client

For OpenClaw

Add to your OpenClaw gateway config:

{
  "mcpServers": {
    "efficient-ticktick": {
      "command": "bunx",
      "args": ["@om-surushe/efficient-ticktick"],
      "env": {
        "TICKTICK_TOKEN": "tp_your_token_here",
        "TIMEZONE": "Asia/Kolkata"
      }
    }
  }
}

For Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "efficient-ticktick": {
      "command": "bunx",
      "args": ["@om-surushe/efficient-ticktick"],
      "env": {
        "TICKTICK_TOKEN": "tp_your_token_here",
        "TIMEZONE": "America/New_York"
      }
    }
  }
}

3. Restart Your Client

The TickTick tools will now be available to your AI assistant!

Available Tools

| Tool | Description | |------|-------------| | get_tasks_today | Get all tasks due today with full time context | | get_overdue_tasks | Get overdue tasks, sorted by urgency | | get_floating_tasks | Get tasks without deadlines | | get_upcoming_tasks | Get tasks due in the next N days | | get_tasks_by_project | Get all tasks in a specific project | | search_tasks | Search tasks by keyword | | suggest_next_task | AI-powered suggestion for what to work on next | | get_task_summary | High-level overview (counts by status) | | create_task | Create new task with flexible date parsing | | complete_task | Mark a task as completed |

Usage Examples

Get Tasks Due Today

Your AI assistant can simply call:

get_tasks_today()

Response includes rich context:

{
  "id": "abc123",
  "title": "Finish project proposal",
  "project": { "name": "💼 Career Growth" },
  "dueDate": {
    "iso": "2026-02-08T17:00:00+05:30",
    "relative": "in 3 hours",
    "userLocal": "Today, 5:00 PM IST"
  },
  "isOverdue": false,
  "priority": "high"
}

Flexible Date Input

Create tasks naturally:

create_task({
  title: "Buy groceries",
  dueDate: "tomorrow",  // Also accepts: "today", "next week", ISO dates
  project: "Personal",
  priority: "medium"
})

Smart Suggestions

suggest_next_task({
  availableMinutes: 30,
  context: "morning"
})

Returns the most relevant task with reasoning:

{
  "task": { /* task details */ },
  "reason": "Due in 2 hours - highest priority",
  "estimatedMinutes": 30
}

Tech Stack

• Runtime: Bun - Fast, modern JavaScript runtime
• Language: TypeScript 5.3+
• Protocol: Model Context Protocol (MCP)
• API: TickTick Open API

Development

# Install dependencies
bun install

# Run in dev mode (with hot reload)
bun run dev

# Build
bun run build

# Run tests
bun test

# Type check
bun run typecheck

# Lint
bun run lint

# Format
bun run format

Testing

# Run all tests
bun test

# Watch mode
bun run test:watch

Contributing

Contributions welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with proper tests
4. Run type checking and tests (bun run typecheck && bun test)
5. Commit with clear messages (git commit -m 'feat: add amazing feature')
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

License

MIT License - see LICENSE for details.

Author

Om Surushe

• GitHub: @om-surushe
• LinkedIn: om-surushe

Acknowledgments

• Built on Model Context Protocol by Anthropic
• Powered by TickTick API

Made with ❤️ and Bun for AI assistants