🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Sunsama
πŸ¦€ ClawHub

Sunsama

by @byungkyu

Sunsama MCP integration with managed authentication. Manage daily tasks, calendar events, backlog, objectives, time tracking, and email threads from connecte...

Versionv1.0.4
Downloads1,350
#crypto-defi#security#legal#communication#productivity
TERMINAL
clawhub install sunsama

πŸ“– About This Skill

name: sunsama description: | Sunsama MCP integration with managed authentication. Manage daily tasks, calendar events, backlog, objectives, time tracking, and email threads from connected accounts (Gmail, Outlook). Use this skill when users want to interact with Sunsama for task management, daily planning, and email thread operations. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). compatibility: Requires network access and valid Maton API key metadata: author: maton version: "1.0" clawdbot: emoji: homepage: "https://maton.ai" requires: env: - MATON_API_KEY

Sunsama MCP

Access Sunsama via MCP (Model Context Protocol) with managed authentication.

Quick Start

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'searchTerm': 'meeting'}).encode()
req = urllib.request.Request('https://api.maton.ai/sunsama/search_tasks', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://api.maton.ai/sunsama/{tool-name}

Maton proxies requests to Sunsama's MCP server and automatically injects your credentials. The {tool-name} corresponds to the MCP tool name (e.g., search_tasks).

Authentication

All requests require the Maton API key:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai 2. Go to maton.ai/settings 3. Copy your API key

Connection Management

Manage your Sunsama MCP connections at https://api.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=sunsama&method=MCP&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'sunsama', 'method': 'MCP'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response: 

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "PENDING",
    "creation_time": "2026-03-03T10:44:23.480898Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "sunsama",
    "method": "MCP",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Security & Permissions

  • Access is scoped to tasks, channels, timers, scheduling data, and email threads within the connected Sunsama account.
  • Email thread access spans connected email accounts. Sunsama can list, read, mark as read, delete, and create follow-up tasks from email threads in linked Gmail or Outlook accounts. Always confirm with the user before performing any email operation, as these actions affect the connected email account directly.
  • All write operations require explicit user approval. Before executing any create, update, or delete call β€” including email deletions and calendar event changes β€” confirm the target resource and intended effect with the user.

    • MCP Reference

    All MCP tools use POST method:

    Task Management

    | Tool | Description | Schema | |------|-------------|--------| | search_tasks | Search tasks by term | schema | | create_task | Create a new task | schema | | edit_task_title | Update task title | schema | | delete_task | Delete a task | schema | | mark_task_as_completed | Mark task complete | schema | | mark_task_as_incomplete | Mark task incomplete | schema | | append_task_notes | Add notes to task | schema | | edit_task_time_estimate | Set time estimate | schema | | edit_task_recurrence_rule | Set recurrence | schema | | get_task_time_estimate | Get AI time estimate | schema | | restore_task | Restore deleted task | schema |

    Subtasks

    | Tool | Description | Schema | |------|-------------|--------| | add_subtasks_to_task | Add subtasks | schema | | edit_subtask_title | Update subtask title | schema | | mark_subtask_as_completed | Mark subtask complete | schema | | mark_subtask_as_incomplete | Mark subtask incomplete | schema |

    Backlog

    | Tool | Description | Schema | |------|-------------|--------| | get_backlog_tasks | List backlog tasks | schema | | move_task_to_backlog | Move task to backlog | schema | | move_task_from_backlog | Move from backlog to day | schema | | reposition_task_in_backlog | Reorder backlog task | schema | | change_backlog_folder | Change task folder | schema | | create_braindump_task | Create backlog task | schema |

    Scheduling

    | Tool | Description | Schema | |------|-------------|--------| | move_task_to_day | Reschedule task | schema | | reorder_tasks | Reorder day's tasks | schema | | timebox_a_task_to_calendar | Block time for task | schema | | set_shutdown_time | Set daily end time | schema |

    Calendar Events

    | Tool | Description | Schema | |------|-------------|--------| | create_calendar_event | Create calendar event | schema | | delete_calendar_event | Delete calendar event | schema | | move_calendar_event | Reschedule event | schema | | import_task_from_calendar_event | Import event as task | schema | | set_calendar_event_allow_task_projections | Toggle task overlap | schema | | accept_meeting_invite | Accept meeting | schema | | decline_meeting_invite | Decline meeting | schema |

    Time Tracking

    | Tool | Description | Schema | |------|-------------|--------| | start_task_timer | Start timer | schema | | stop_task_timer | Stop timer | schema |

    Channels & Objectives

    | Tool | Description | Schema | |------|-------------|--------| | create_channel | Create channel/context | schema | | add_task_to_channel | Assign task to channel | schema | | create_weekly_objective | Create weekly goal | schema | | align_task_with_objective | Link task to objective | schema |

    Archive

    | Tool | Description | Schema | |------|-------------|--------| | get_archived_tasks | List archived tasks | schema | | unarchive_task | Restore archived task | schema |

    Email Integration

    | Tool | Description | Schema | |------|-------------|--------| | list_email_threads | List email threads | schema | | create_follow_up_task_from_email | Create task from email | schema | | delete_email_thread | Delete email thread | schema | | mark_email_thread_as_read | Mark email as read | schema |

    Recurring Tasks

    | Tool | Description | Schema | |------|-------------|--------| | delete_all_incomplete_recurring_task_instances | Delete future recurrences | schema | | update_all_incomplete_recurring_task_instances | Update future recurrences | schema |

    Settings & Preferences

    | Tool | Description | Schema | |------|-------------|--------| | toggle_auto_import_events | Toggle event auto-import | schema | | update_calendar_preferences | Update calendar settings | schema | | update_import_event_filters | Set event filters | schema | | log_user_feedback | Submit feedback | schema |

    Common Endpoints

    Search Tasks

    Search for tasks by keyword: 

    POST /sunsama/search_tasks
Content-Type: application/json
    {
  "searchTerm": "meeting"
}

    Response: 

    {
  "content": [
    {
      "type": "text",
      "text": "{\"tasks\":[{\"_id\":\"69a6bf3a04d3cd0001595308\",\"title\":\"Team meeting prep\",\"scheduledDate\":\"2026-03-03\",\"completed\":false}]}"
    }
  ],
  "isError": false
}

    Create Task

    Create a new task scheduled for a specific day: 

    POST /sunsama/create_task
Content-Type: application/json
    {
  "title": "Review quarterly report",
  "day": "2026-03-03",
  "alreadyInTaskList": false
}

    Response: 

    {
  "content": [
    {
      "type": "text",
      "text": "{\"success\":true,\"task\":{\"_id\":\"69a6bf3a04d3cd0001595308\",\"title\":\"Review quarterly report\",\"notes\":\"\",\"timeEstimate\":\"20 minutes\",\"sortOrder\":-1772535610535,\"isPersonal\":false,\"isWork\":true,\"isPrivate\":false,\"isArchived\":false,\"completed\":false,\"isBacklogged\":false,\"scheduledDate\":\"2026-03-03\",\"subtasks\":[],\"channel\":\"work\",\"folder\":null,\"timeboxEventIds\":[]}}"
    }
  ],
  "isError": false
}

    Get Backlog Tasks

    List all tasks in the backlog: 

    POST /sunsama/get_backlog_tasks
Content-Type: application/json
    {}

    Response: 

    {
  "content": [
    {
      "type": "text",
      "text": "{\"tasks\":[],\"queryId\":\"bb7d004a-0b29-49d9-8345-6d9037786fbb\",\"totalPages\":1}"
    }
  ],
  "isError": false
}

    Mark Task as Completed

    POST /sunsama/mark_task_as_completed
Content-Type: application/json
    {
  "taskId": "69a6bf3a04d3cd0001595308",
  "finishedDay": "2026-03-03"
}

    Add Subtasks to Task

    POST /sunsama/add_subtasks_to_task
Content-Type: application/json
    {
  "taskId": "69a6bf3a04d3cd0001595308",
  "subtasks": [
    {"title": "Step 1: Research"},
    {"title": "Step 2: Draft outline"},
    {"title": "Step 3: Review"}
  ]
}

    Create Calendar Event

    POST /sunsama/create_calendar_event
Content-Type: application/json
    {
  "title": "Team standup",
  "startDate": "2026-03-03T09:00:00"
}

    Move Task to Day

    Reschedule a task to a different day: 

    POST /sunsama/move_task_to_day
Content-Type: application/json
    {
  "taskId": "69a6bf3a04d3cd0001595308",
  "calendarDay": "2026-03-04"
}

    Timebox Task to Calendar

    Block time for a task on your calendar: 

    POST /sunsama/timebox_a_task_to_calendar
Content-Type: application/json
    {
  "taskId": "69a6bf3a04d3cd0001595308",
  "startDate": "2026-03-03",
  "startTime": "14:00"
}

    Create Weekly Objective

    POST /sunsama/create_weekly_objective
Content-Type: application/json
    {
  "title": "Complete Q1 planning",
  "weekStartDay": "2026-03-03"
}

    Create Braindump Task (Backlog)

    Add a task to backlog with time bucket: 

    POST /sunsama/create_braindump_task
Content-Type: application/json
    {
  "title": "Research new tools",
  "timeBucket": "in the next month"
}

    Time bucket options:

  • "in the next two weeks"
  • "in the next month"
  • "in the next quarter"
  • "in the next year"
  • "someday"
  • "never"

    • Start/Stop Task Timer

    POST /sunsama/start_task_timer
Content-Type: application/json
    {
  "taskId": "69a6bf3a04d3cd0001595308"
}


    POST /sunsama/stop_task_timer
Content-Type: application/json
    {
  "taskId": "69a6bf3a04d3cd0001595308"
}

    Set Shutdown Time

    Set when your workday ends: 

    POST /sunsama/set_shutdown_time
Content-Type: application/json
    {
  "calendarDay": "2026-03-03",
  "hour": 18,
  "minute": 0
}

    Code Examples

    JavaScript

    const response = await fetch('https://api.maton.ai/sunsama/search_tasks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': Bearer ${process.env.MATON_API_KEY}
  },
  body: JSON.stringify({
    searchTerm: 'meeting'
  })
});
const data = await response.json();
console.log(data);

    Python

    import os
import requests
    response = requests.post(
    'https://api.maton.ai/sunsama/search_tasks',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'searchTerm': 'meeting'
    }
)
print(response.json())

    Error Handling

    | Status | Meaning | |--------|---------| | 400 | Missing MCP connection or invalid tool name | | 401 | Invalid or missing Maton API key | | 429 | Rate limited |

    Troubleshooting: API Key Issues

    1. Check that the MATON_API_KEY environment variable is set:

    echo $MATON_API_KEY

    2. Verify the API key is valid by listing connections:

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    Notes

  • All task IDs are MongoDB ObjectIds (24-character hex strings)
  • Date format: YYYY-MM-DD for days, ISO 8601 for datetimes
  • MCP tool responses wrap content in {"content": [{"type": "text", "text": "..."}], "isError": false} format
  • The text field contains JSON-stringified data that should be parsed
  • Time estimates are returned as human-readable strings (e.g., "20 minutes")

    • Resources

  • Sunsama
  • Maton Community
  • Maton Support

    • πŸ’‘ Examples

    python <<'EOF'
import urllib.request, os, json
data = json.dumps({'searchTerm': 'meeting'}).encode()
req = urllib.request.Request('https://api.maton.ai/sunsama/search_tasks', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    πŸ“‹ Tips & Best Practices

  • All task IDs are MongoDB ObjectIds (24-character hex strings)
  • Date format: YYYY-MM-DD for days, ISO 8601 for datetimes
  • MCP tool responses wrap content in {"content": [{"type": "text", "text": "..."}], "isError": false} format
  • The text field contains JSON-stringified data that should be parsed
  • Time estimates are returned as human-readable strings (e.g., "20 minutes")