Sunsama

You can run Sunsama MCP Server to access Sunsama tasks through AI assistants, create and manage tasks, and streamline your productivity workflow via a flexible MCP transport that supports both local (stdio) and HTTP connections.

How to use

This server lets you interact with Sunsama through your preferred MCP client. Use the HTTP transport for remote integrations or the stdio transport for local AI assistants. You can create tasks with notes and deadlines, read today’s tasks or backlog, update task statuses, manage subtasks, and delete tasks. You can also retrieve user and stream information to better organize your projects.

How to install

Prerequisites: you need Bun as the runtime for development and a Sunsama account with API access.

# Recommended: run directly with NPX (no install required)
npx mcp-sunsama

# Development setup (clone and run commands shown in order)
git clone https://github.com/robertn702/mcp-sunsama.git
cd mcp-sunsama
bun install
cp .env.example .env
# Edit .env to add your Sunsama credentials

Configuration and startup

Configure environment variables according to how you plan to connect. The server supports two transport modes: stdio (default) and http. You can switch by setting TRANSPORT_MODE to stdio or http.

SUNSAMA_EMAIL=your-email@example.com
SUNSAMA_PASSWORD=your-password
TRANSPORT_MODE=stdio
PORT=8080
HTTP_ENDPOINT=/mcp
SESSION_TTL=3600000
CLIENT_IDLE_TIMEOUT=900000
MAX_SESSIONS=100

Usage with HTTP transport

To enable remote access, start the server with HTTP transport. The MCP endpoint is exposed at the specified port and path, and requests require HTTP Basic Authentication using your Sunsama credentials.

TRANSPORT_MODE=http PORT=8080 bun run src/main.ts

Usage with stdio transport

For local AI assistants, keep stdio transport as the default. Start the server using the standard NPX-based command.

bun run dev
# or
TRANSPORT_MODE=stdio bun run src/main.ts

Claude integration configuration

If you use Claude Desktop, configure the Sunsama MCP server with the provided settings. This establishes a local stdio-based MCP connection.

{
  "mcpServers": {
    "sunsama": {
      "command": "npx",
      "args": ["mcp-sunsama"],
      "env": {
        "SUNSAMA_EMAIL": "your-email@example.com",
        "SUNSAMA_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code configuration

In Claude Code, add Sunsama MCP as a server to access Sunsama tasks from within the editor.

claude mcp add sunsama --scope user \
  -e SUNSAMA_EMAIL=your-email@example.com \
  -e SUNSAMA_PASSWORD=your-password \
-- npx mcp-sunsama

API tools and capabilities

The server provides a comprehensive set of tools to manage tasks, subtasks, and streams, including creating tasks, reading tasks by day or backlog, updating task details, adding subtasks, and deleting tasks. It also supports retrieving user and stream information.

Notes on security and sessions

Security is handled via HTTP Basic Auth for HTTP transport and per-request credentials for stdio transport. Session and token handling are managed with TTL-based lifecycles to balance performance and security for HTTP connections.

Notes on development and testing

Development uses Bun. Run tests with the provided scripts and perform type checks and builds as part of your workflow to ensure compatibility with SunSama APIs and MCP clients.

Available tools

create-task

Create a new task with optional notes, time estimates, due date, stream assignment, and available integrations like GitHub or Gmail.

get-tasks-by-day

Fetch tasks for a specific day with optional completion filtering.

get-tasks-backlog

Retrieve backlog tasks for review and planning.

get-archived-tasks

Fetch archived tasks with pagination support and a hasMore flag for context.

get-task-by-id

Retrieve a single task by its unique identifier.

update-task-complete

Mark a task as complete with optional timestamp.

update-task-planned-time

Update the planned time or time estimate for a task.

update-task-notes

Update task notes content, supporting either HTML or Markdown formats (mutually exclusive).

update-task-due-date

Set or clear a due date for a task.

update-task-text

Update the text or title of a task.

update-task-stream

Change the stream or channel assignment for a task.

update-task-snooze-date

Reschedule a task to a different date.

update-task-backlog

Move a task to the backlog.

delete-task

Permanently delete a task.

add-subtask

Create a single subtask within a task.

create-subtasks

Create multiple subtasks for a task.

update-subtask-title

Update a subtask title.

complete-subtask

Mark a subtask as complete with an optional timestamp.

uncomplete-subtask

Mark a subtask as incomplete.

get-user

Retrieve current user information.

get-streams

Retrieve streams or channels for project organization.