Sunsama MCP Server

A Model Context Protocol (MCP) server that provides comprehensive task management capabilities through the Sunsama API. This server enables AI assistants to access Sunsama tasks, create new tasks, mark tasks complete, and manage your productivity workflow.

Features

Task Management

Create Tasks - Create new tasks with notes, time estimates, due dates, stream assignments, and GitHub/Gmail integrations
Read Tasks - Get tasks by day with completion filtering, access backlog tasks, retrieve archived task history
Update Tasks - Mark tasks as complete with custom timestamps, reschedule tasks or move to backlog
Delete Tasks - Permanently remove tasks from your workspace

User & Stream Operations

User Information - Access user profile, timezone, and group details
Stream Management - Get streams/channels for project organization
Dual Transport - Support for both stdio and HTTP stream MCP transports

Related MCP server: DeltaTask MCP Server

Installation

Prerequisites

Bun runtime (for development)
Sunsama account with API access

Using NPX (Recommended)

No installation required! Use directly with:

npx mcp-sunsama

Development Setup

Clone the repository:

git clone https://github.com/robertn702/mcp-sunsama.git cd mcp-sunsama

Install dependencies:

bun install

Set up your environment variables:

cp .env.example .env # Edit .env and add your Sunsama credentials

Environment variables:

SUNSAMA_EMAIL - Your Sunsama account email (required for stdio transport)
SUNSAMA_PASSWORD - Your Sunsama account password (required for stdio transport)
TRANSPORT_MODE - Transport type: stdio (default) or http
PORT - Server port for HTTP transport (default: 8080)
HTTP_ENDPOINT - MCP endpoint path (default: /mcp)
SESSION_TTL - Session timeout in milliseconds (default: 3600000 / 1 hour)
CLIENT_IDLE_TIMEOUT - Client idle timeout in milliseconds (default: 900000 / 15 minutes)
MAX_SESSIONS - Maximum concurrent sessions for HTTP transport (default: 100)

Usage

Transport Modes

This server supports two transport modes:

Stdio Transport (Default)

For local AI assistants (Claude Desktop, Cursor, etc.):

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

HTTP Stream Transport

For remote access and web-based integrations:

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

HTTP Endpoints:

MCP Endpoint: POST http://localhost:8080/mcp
Health Check: GET http://localhost:8080/

Authentication: HTTP requests require HTTP Basic Auth with your Sunsama credentials:

curl -X POST http://localhost:8080/mcp \ -H "Authorization: Basic $(echo -n 'your-email:your-password' | base64)" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Claude Desktop Configuration

Add this configuration to your Claude Desktop MCP settings:

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

API Tools

Task Management

create-task - Create new tasks with optional properties including GitHub issue/PR and Gmail integration
get-tasks-by-day - Get tasks for a specific day with completion filtering
get-tasks-backlog - Get backlog tasks
get-archived-tasks - Get archived tasks with pagination (includes hasMore flag for LLM context)
get-task-by-id - Get a specific task by its ID
update-task-complete - Mark tasks as complete
update-task-planned-time - Update the planned time (time estimate) for tasks
update-task-notes - Update task notes content (requires either html or markdown parameter, mutually exclusive)
update-task-due-date - Update the due date for tasks (set or clear due dates)
update-task-text - Update the text/title of tasks
update-task-stream - Update the stream/channel assignment for tasks
update-task-snooze-date - Reschedule tasks to different dates
update-task-backlog - Move tasks to the backlog
delete-task - Delete tasks permanently

User & Stream Operations

get-user - Get current user information
get-streams - Get streams/channels for project organization

Integration Examples

The create-task tool supports linking tasks to external services like GitHub and Gmail.

GitHub Integration

Link a task to a GitHub issue:

{ "text": "Fix authentication bug", "integration": { "service": "github", "identifier": { "id": "I_kwDOO4SCuM7VTB4n", "repositoryOwnerLogin": "robertn702", "repositoryName": "mcp-sunsama", "number": 42, "type": "Issue", "url": "https://github.com/robertn702/mcp-sunsama/issues/42", "__typename": "TaskGithubIntegrationIdentifier" }, "__typename": "TaskGithubIntegration" } }

Link a task to a GitHub pull request:

{ "text": "Review API refactoring PR", "integration": { "service": "github", "identifier": { "id": "PR_kwDOO4SCuM7VTB5o", "repositoryOwnerLogin": "robertn702", "repositoryName": "mcp-sunsama", "number": 15, "type": "PullRequest", "url": "https://github.com/robertn702/mcp-sunsama/pull/15", "__typename": "TaskGithubIntegrationIdentifier" }, "__typename": "TaskGithubIntegration" } }

Gmail Integration

Link a task to a Gmail email:

{ "text": "Respond to project update email", "integration": { "service": "gmail", "identifier": { "id": "19a830b40fd7ab7d", "messageId": "19a830b40fd7ab7d", "accountId": "user@example.com", "url": "https://mail.google.com/mail/u/user@example.com/#inbox/19a830b40fd7ab7d", "__typename": "TaskGmailIntegrationIdentifier" }, "__typename": "TaskGmailIntegration" } }

Note: All integration parameters are optional. Tasks can be created without integrations for standard task management.

Development

Running in Development

bun run dev

Testing with MCP Inspector

bun run inspect

Then connect the MCP Inspector to test the tools interactively.

Testing

bun test # Run unit tests only bun test:unit # Run unit tests only (alias) bun test:integration # Run integration tests (requires credentials) bun test:all # Run all tests bun test:watch # Watch mode for unit tests

Build and Type Checking

bun run build # Compile TypeScript to dist/ bun run typecheck # Run TypeScript type checking bun run typecheck:watch # Watch mode type checking

Release Process

For information on creating releases and publishing to npm, see CONTRIBUTING.md.

Code Architecture

The server is organized with a modular, resource-based architecture:

src/ ├── tools/ │ ├── shared.ts # Common utilities and patterns │ ├── user-tools.ts # User operations (get-user) │ ├── task-tools.ts # Task operations (15 tools) │ ├── stream-tools.ts # Stream operations (get-streams) │ └── index.ts # Export all tools ├── resources/ │ └── index.ts # API documentation resource ├── auth/ # Authentication strategies │ ├── stdio.ts # Stdio transport authentication │ ├── http.ts # HTTP Basic Auth parsing │ └── types.ts # Shared auth types ├── transports/ │ ├── stdio.ts # Stdio transport implementation │ └── http.ts # HTTP Stream transport with session management ├── session/ │ └── session-manager.ts # Session lifecycle management ├── config/ # Environment configuration │ ├── transport.ts # Transport mode configuration │ └── session-config.ts # Session TTL configuration ├── utils/ # Utilities (filtering, trimming, etc.) │ ├── client-resolver.ts # Transport-agnostic client resolution │ ├── task-filters.ts # Task completion filtering │ ├── task-trimmer.ts # Response size optimization │ └── to-tsv.ts # TSV formatting utilities ├── schemas.ts # Zod validation schemas └── main.ts # Server setup (47 lines vs 1162 before refactoring) __tests__/ ├── unit/ # Unit tests (no auth required) │ ├── auth/ # Auth utility tests │ ├── config/ # Configuration tests │ └── session/ # Session management tests └── integration/ # Integration tests (requires credentials) └── http-transport.test.ts

Key Features:

Type Safety: Full TypeScript typing with Zod schema validation
Parameter Destructuring: Clean, explicit function signatures
Shared Utilities: Common patterns extracted to reduce duplication
Error Handling: Standardized error handling across all tools
Response Optimization: Task filtering and trimming for large datasets
Session Management: Dual-layer caching with TTL-based lifecycle management
Test Coverage: 251+ unit tests and comprehensive integration tests

Authentication

Stdio Transport: Requires SUNSAMA_EMAIL and SUNSAMA_PASSWORD environment variables.

HTTP Transport: Credentials provided via HTTP Basic Auth per request. No environment variables needed for credentials.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines on:

Development workflow
Code style and conventions
Testing requirements
Release process (for maintainers)

Quick start:

Fork and clone the repository
Install dependencies: bun install
Make your changes
Create a changeset: bun run changeset
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

sunsama-api Library - The underlying API client
Model Context Protocol Documentation
Issue Tracker

Sunsama MCP Server

Sunsama MCP Server

Features

Task Management

User & Stream Operations

Installation

Prerequisites

Using NPX (Recommended)

Development Setup

Usage

Transport Modes

Stdio Transport (Default)

HTTP Stream Transport

Claude Desktop Configuration

API Tools

Task Management

User & Stream Operations

Integration Examples

GitHub Integration

Gmail Integration

Development

Running in Development

Testing with MCP Inspector

Testing

Build and Type Checking

Release Process

Code Architecture

Authentication

Contributing

License

Support

Related Resources

Tools

New MCP Servers

MCP directory API