sunsama-mcp

MCP server for Cursor that creates tasks on today's Sunsama list by sending email to your Sunsama forwarding address.

Prerequisites

• Node.js 18+
• A Sunsama account with email forwarding enabled (the "today" address)
• An SMTP account (Gmail with an App Password works well)

Installation

Option A: npx (no clone needed)

No install required. Configure Cursor to run the package directly:

{
  "mcpServers": {
    "sunsama-email": {
      "command": "npx",
      "args": ["-y", "@oleh-polishchuk/sunsama-mcp"],
      "env": {
        "SUNSAMA_EMAIL": "[email protected]",
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_SECURE": "false",
        "SMTP_USER": "[email protected]",
        "SMTP_APP_PASSWORD": "xxxx xxxx xxxx xxxx"
      }
    }
  }
}

Option B: global install

npm install -g @oleh-polishchuk/sunsama-mcp

Then add to Cursor MCP settings:

{
  "mcpServers": {
    "sunsama-email": {
      "command": "sunsama-mcp",
      "env": {
        "SUNSAMA_EMAIL": "[email protected]",
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_SECURE": "false",
        "SMTP_USER": "[email protected]",
        "SMTP_APP_PASSWORD": "xxxx xxxx xxxx xxxx"
      }
    }
  }
}

Option C: clone and build (for contributors)

git clone https://github.com/olehpolishchuk/sunsama-mcp.git
cd sunsama-mcp
npm install
cp .env.example .env
# Fill in your values in .env (see Configuration below)
npm run build

Then add to Cursor MCP settings:

{
  "mcpServers": {
    "sunsama-email": {
      "command": "node",
      "args": ["/absolute/path/to/sunsama-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/sunsama-mcp"
    }
  }
}

The cwd must point to the project root so .env loads correctly.

Configuration

You can provide configuration either through the env field in your Cursor MCP settings (Options A and B) or through a .env file in the project root (Option C).

| Variable | Required | Description | | ------------------- | -------- | -------------------------------------------------------------- | | SUNSAMA_EMAIL | Yes | Your Sunsama "today" forwarding address | | SMTP_HOST | Yes | SMTP server host (e.g. smtp.gmail.com) | | SMTP_PORT | Yes | SMTP port (465 for SSL, 587 for STARTTLS) | | SMTP_SECURE | Yes | true for port 465, false for port 587 | | SMTP_USER | Yes | SMTP login username | | SMTP_APP_PASSWORD | Yes | SMTP App Password (not your account password) | | SMTP_FROM | No | From address; defaults to SMTP_USER | | DRY_RUN | No | Set to true to validate without sending; defaults to false |

Gmail setup

1. Enable 2-Step Verification on your Google Account.
2. Go to App Passwords.
3. Create an App Password for "Mail".
4. Use that 16-character password as SMTP_APP_PASSWORD.

Finding your Sunsama forwarding address

1. Open Sunsama.
2. Go to Settings > Integrations > Email.
3. Copy the forwarding address labeled for "today's" list.

Dry-run test

1. Set DRY_RUN=true (in .env or in the Cursor env config).
2. In Cursor, call the create_sunsama_task tool with a test title.
3. Confirm the response shows "dryRun": true and no email was sent.

Live test

1. Set DRY_RUN=false (or remove it; it defaults to false).
2. In Cursor, call create_sunsama_task with title "Test from MCP".
3. Check your Sunsama today list; the task should appear within a few seconds.

Available tools

create_sunsama_task

Creates a task on today's Sunsama list.

Parameters:

• title (string, required): Task name. Max 200 characters.
• description (string, optional): Task body. Max 50,000 characters.

Running tests

npm test

Troubleshooting

"Missing required environment variables"

The server validates all required env vars on startup. Check that all required values are set, either in your .env file or in the Cursor env config.

"SMTP authentication failed"

• Confirm SMTP_USER and SMTP_APP_PASSWORD are correct.
• For Gmail: you need an App Password, not your regular password. App Passwords require 2-Step Verification.
• Check that "Less secure app access" is not the method you're relying on (Google deprecated it).

"SMTP connection timed out" or "connection refused"

• Verify SMTP_HOST and SMTP_PORT are correct.
• Check your firewall and network; some networks block outbound SMTP.
• For Gmail: use smtp.gmail.com with port 587 (STARTTLS) or 465 (SSL).

Task doesn't appear in Sunsama

• Verify SUNSAMA_EMAIL is your "today" forwarding address (not the backlog address).
• Check your spam folder; the email might have been filtered.
• Wait a minute; Sunsama processes forwarded emails with a short delay.

Server doesn't start in Cursor

• For npx/global installs: check that all env vars are set in the Cursor env config.
• For cloned repos: make sure cwd in your Cursor config points to the project root.
• Run node dist/index.js manually from the project root to see startup errors on stderr.
• Check that you ran npm run build after any changes.

License

MIT