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
- Subtasks - Add, update, complete, and manage subtasks within tasks
- 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
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) orhttpPORT- 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"
}
}
}
}
Claude Code Configuration
Add the Sunsama MCP server using the Claude Code CLI:
claude mcp add sunsama --scope user \
-e SUNSAMA_EMAIL=your-email@example.com \
-e SUNSAMA_PASSWORD=your-password \
-- npx mcp-sunsama
Scope Options:
--scope user- Available across all projects (recommended)--scope project- Only available in the current project
After adding the server, restart Claude Code to connect to the Sunsama MCP server.
API Tools
Task Management
create-task- Create new tasks with optional properties including GitHub issue/PR and Gmail integrationget-tasks-by-day- Get tasks for a specific day with completion filteringget-tasks-backlog- Get backlog tasksget-archived-tasks- Get archived tasks with pagination (includes hasMore flag for LLM context)get-task-by-id- Get a specific task by its IDupdate-task-complete- Mark tasks as completeupdate-task-planned-time- Update the planned time (time estimate) for tasksupdate-task-notes- Update task notes content (requires eitherhtmlormarkdownparameter, 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 tasksupdate-task-stream- Update the stream/channel assignment for tasksupdate-task-snooze-date- Reschedule tasks to different datesupdate-task-backlog- Move tasks to the backlogdelete-task- Delete tasks permanently
Subtask Management
add-subtask- Create a subtask with a title in one call (recommended for single subtask creation)create-subtasks- Create multiple subtasks for a task (low-level API for bulk operations)update-subtask-title- Update the title of a subtaskcomplete-subtask- Mark a subtask as complete with optional completion timestampuncomplete-subtask- Mark a subtask as incomplete
User & Stream Operations
get-user- Get current user informationget-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