npm package: @oleh-polishchuk/sunsama-mcp
Description: MCP server that creates Sunsama tasks via email forwarding
Latest version: 1.0.0

# 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:

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

### Option B: global install

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

Then add to Cursor MCP settings:

```json
{
  "mcpServers": {
    "sunsama-email": {
      "command": "sunsama-mcp",
      "env": {
        "SUNSAMA_EMAIL": "your+forwarding@email.sunsama.com",
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_SECURE": "false",
        "SMTP_USER": "you@gmail.com",
        "SMTP_APP_PASSWORD": "xxxx xxxx xxxx xxxx"
      }
    }
  }
}
```

### Option C: clone and build (for contributors)

```bash
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:

```json
{
  "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](https://myaccount.google.com/apppasswords).
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

```bash
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