On this page

TaskCalendars provides a Model Context Protocol (MCP) server that allows AI assistants like Claude, GPT, and other LLMs to interact with your tasks and calendars programmatically.

What is MCP?

The Model Context Protocol (MCP) is a standard that enables AI assistants to safely interact with external services. With TaskCalendars MCP, your AI assistant can:

  • List and search tasks across your calendars
  • Create new tasks with full details
  • Update existing tasks including status changes
  • Query task instances for specific date ranges
  • Manage task members and assignments

Setting Up MCP

Prerequisites

  1. A TaskCalendars account with API access
  2. An AI assistant that supports MCP (e.g., Claude Desktop, Cursor, Windsurf)
  3. Your API token from TaskCalendars

Getting Your API Token

  1. Go to Settings in TaskCalendars
  2. Navigate to API Access
  3. Click Generate New Token
  4. Copy the token securely - it won’t be shown again

Configuration

Add the TaskCalendars MCP server to your AI assistant’s configuration:

Claude Desktop / Cursor / Windsurf

Add to your MCP configuration file:

{
  "mcpServers": {
    "taskcalendars": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-server-fetch",
        "https://app.taskcalendars.com/api/mcp"
      ],
      "env": {
        "AUTHORIZATION": "Bearer YOUR_API_TOKEN_HERE"
      }
    }
  }
}

Alternative: Using mcp-proxy

{
  "mcpServers": {
    "taskcalendars": {
      "command": "mcp-proxy",
      "args": ["https://app.taskcalendars.com/api/mcp"],
      "env": {
        "AUTHORIZATION": "Bearer YOUR_API_TOKEN_HERE"
      }
    }
  }
}

Available Tools

Once configured, your AI assistant will have access to these tools:

list_calendars

Lists all calendars you have access to.

Example prompt: “Show me all my TaskCalendars calendars”

get_calendar

Gets details about a specific calendar including settings and permissions.

Parameters:

  • calendar_id - The ID of the calendar

Example prompt: “Get details for the Marketing calendar”

list_tasks

Lists tasks from a calendar with optional filtering.

Parameters:

  • calendar_id - The calendar to list tasks from
  • status (optional) - Filter by status
  • assignee_id (optional) - Filter by assigned member

Example prompt: “Show me all incomplete tasks in the Q1 Planning calendar”

get_task

Gets full details of a specific task.

Parameters:

  • task_id - The ID of the task

Example prompt: “Show me the details of task TC-1234”

search_tasks

Searches for tasks by name or description.

Parameters:

  • query - Search term
  • calendar_id (optional) - Limit search to specific calendar

Example prompt: “Find all tasks mentioning ‘budget review’”

create_task

Creates a new task.

Parameters:

  • calendar_id - Calendar to create the task in
  • name - Task name
  • description (optional) - Task description
  • due_date (optional) - Due date in ISO format
  • assignee_ids (optional) - Array of member IDs to assign

Example prompt: “Create a task called ‘Review Q2 reports’ in the Finance calendar, due next Friday”

update_task

Updates an existing task.

Parameters:

  • task_id - The ID of the task to update
  • name (optional) - New task name
  • description (optional) - New description
  • status (optional) - New status
  • due_date (optional) - New due date

Example prompt: “Mark task TC-1234 as completed”

list_task_instances

Lists task instances (occurrences) within a date range.

Parameters:

  • calendar_id - The calendar to query
  • start_date - Start of date range (ISO format)
  • end_date - End of date range (ISO format)

Example prompt: “What tasks are due this week in the Operations calendar?”

list_task_members

Lists members assigned to a specific task.

Parameters:

  • task_id - The ID of the task

Example prompt: “Who is assigned to task TC-1234?”

Example Conversations

Creating Tasks

You: Create a new task in my “Project Alpha” calendar called “Design review meeting” with description “Review the new UI designs with the team” due on January 30th.

AI Assistant: I’ll create that task for you.

[Uses create_task tool]

Done! I’ve created the task “Design review meeting” in your Project Alpha calendar, due January 30th.

Checking Status

You: What tasks do I have due this week?

AI Assistant: Let me check your upcoming tasks.

[Uses list_task_instances tool with current week’s date range]

You have 5 tasks due this week:

  1. Budget review - Due Monday
  2. Team standup notes - Due Tuesday
  3. Client presentation - Due Wednesday
  4. Design review meeting - Due Thursday
  5. Weekly report - Due Friday

Bulk Updates

You: Mark all tasks in the “Sprint 12” calendar that contain “bug fix” as completed.

AI Assistant: I’ll search for those tasks and update them.

[Uses search_tasks then update_task for each match]

Done! I’ve marked 3 tasks as completed:

  • Bug fix: Login timeout issue
  • Bug fix: Dashboard loading error
  • Bug fix: Export formatting

Security Notes

  • Your API token grants access to all calendars and tasks you have permission for
  • Never share your API token publicly
  • Tokens can be revoked at any time from Settings > API Access
  • All MCP requests are logged for security auditing
  • Rate limits apply: 100 requests per minute

Troubleshooting

“Unauthorized” errors

  • Verify your API token is correct
  • Check that the token hasn’t been revoked
  • Ensure the Authorization header format is correct: Bearer YOUR_TOKEN

“Calendar not found” errors

  • Verify the calendar_id is correct
  • Check that you have access to the calendar

Tools not appearing

  • Restart your AI assistant after configuration changes
  • Verify the MCP server URL is correct
  • Check your network can reach app.taskcalendars.com

Rate Limits

To ensure fair usage:

  • 100 requests per minute per API token
  • 1000 requests per hour per API token
  • Bulk operations count as multiple requests

If you hit rate limits, the API will return a 429 status code. Wait a moment before retrying.