Used as the runtime environment for the MCP server, providing fast JavaScript/TypeScript execution for the Sunsama integration.
Supports environment variable configuration for authentication and server settings through .env files.
Used for version control and development workflow of the MCP-Sunsama project.
Source code repository hosting for the MCP-Sunsama project with issue tracking capabilities.
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, and stream assignments
- 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
Installation
Prerequisites
- Bun runtime (for development)
- Sunsama account with API access
Using NPX (Recommended)
No installation required! Use directly with:
Development Setup
- Clone the repository:
- Install dependencies:
- Set up your environment variables:
Environment variables:
SUNSAMA_EMAIL
- Your Sunsama account email (required for stdio transport)SUNSAMA_PASSWORD
- Your Sunsama account password (required for stdio transport)SUNSAMA_SESSION_TOKEN
- Alternative session token authentication (optional)PORT
- Server port for HTTP transport (default: 3002)MCP_TRANSPORT
- Transport type:stdio
orhttpStream
(default: stdio)
Usage
Running the Server
Stdio Transport (default):
HTTP Stream Transport:
Claude Desktop Configuration
Add this configuration to your Claude Desktop MCP settings:
API Tools
Task Management
create-task
- Create new tasks with optional propertiesget-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 eitherhtml
ormarkdown
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 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
User & Stream Operations
get-user
- Get current user informationget-streams
- Get streams/channels for project organization
Development
Running in Development
Testing with MCP Inspector
Then connect the MCP Inspector to test the tools interactively.
Build and Type Checking
Code Architecture
The server is organized with a modular, resource-based architecture:
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
Authentication
Stdio Transport: Requires SUNSAMA_EMAIL
and SUNSAMA_PASSWORD
environment variables.
HTTP Transport: The Sunsama credentials are passed in the HTTP request. No environment variables needed.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- 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
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Enables AI assistants to manage tasks in Sunsama, including creating tasks, reading daily and backlog tasks, marking tasks complete, and organizing projects through streams.
Related MCP Servers
- AsecurityAlicenseAqualityProvides API access to a locally-hosted task management system with features for creating, updating, and organizing tasks, including support for urgency levels, effort estimates, subtasks, and bi-directional sync with Obsidian markdown files.Last updated -123PythonMIT License
- -securityFlicense-qualityProvides tools for AI assistants to interact with the Dida365 (TickTick) task management API, allowing management of tasks and projects after user authorization.Last updated -14JavaScript
- -securityAlicense-qualityThis server implementation allows AI assistants to interact with Asana's API, enabling users to manage tasks, projects, workspaces, and comments through natural language requests.Last updated -189TypeScriptMIT License
- -securityAlicense-qualityAI-driven task management application that operates via MCP, enabling autonomous creation, organization, and execution of tasks with support for subtasks, priorities, and progress tracking.Last updated -PythonMIT License