# Comms MCP & AI Tools

MCP server and importable AI tools for the Todoist Comms API. Use the
tools through an MCP server, or import them directly to plug Comms into
your own AI conversational interface.

## Using as an MCP server

**MCP server URL (Streamable HTTP):** `https://ai.todoist.net/mcp/comms`

Add it to your AI client and sign in with your Todoist account. You
don't need an API key or to run the server yourself.

### Claude Desktop

1. Open Settings → Connectors → Add custom connector
2. Enter `https://ai.todoist.net/mcp/comms` and complete OAuth
   authentication

### Claude Code (CLI)

```bash
claude mcp add --transport http comms https://ai.todoist.net/mcp/comms
```

Then launch `claude`, run `/mcp`, and select the `comms` server to
authenticate.

### Cursor

`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):

```json
{
    "mcpServers": {
        "comms": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://ai.todoist.net/mcp/comms"]
        }
    }
}
```

### Visual Studio Code

Run **MCP: Add Server** from the Command Palette, pick HTTP, and enter
the URL. Or add it to `.vscode/mcp.json`:

```json
{
    "servers": {
        "comms": {
            "type": "http",
            "url": "https://ai.todoist.net/mcp/comms"
        }
    }
}
```

### Other MCP clients

```bash
npx -y mcp-remote https://ai.todoist.net/mcp/comms
```

### Running it locally

To run the server yourself over stdio, pass it a
[Comms API key](#getting-a-comms-api-key):

```json
{
    "mcpServers": {
        "comms": {
            "command": "npx",
            "args": ["-y", "@todoist/comms-mcp"],
            "env": {
                "COMMS_API_KEY": "your-comms-api-key-here"
            }
        }
    }
}
```

VS Code uses `servers` instead of `mcpServers`. In Claude Code:

```bash
claude mcp add comms npx @todoist/comms-mcp
export COMMS_API_KEY=your-comms-api-key-here
```

#### Targeting a non-production deployment

By default the server talks to `https://comms.todoist.com`. To point at
staging or a custom deployment, also set `COMMS_BASE_URL`:

```json
"env": {
    "COMMS_API_KEY": "your-comms-api-key-here",
    "COMMS_BASE_URL": "https://comms.staging.todoist.com"
}
```

#### Getting a Comms API key

Comms accepts your Todoist API token. In Todoist, open **Settings →
Integrations → Developer** and copy the API token, then export it as
`COMMS_API_KEY` (or paste it into the MCP client config above). It has
full access to your account, so keep it secret.

## Using the tools

### 1. Install

```sh
npm install @todoist/comms-mcp
```

This package was previously published as `@doist/comms-mcp`.

### 2. Plug them into an AI

Example with [Vercel's AI SDK](https://ai-sdk.dev/docs/ai-sdk-core/generating-text#streamtext):

```js
import { fetchInbox, reply, markDone } from '@todoist/comms-mcp'
import { streamText } from 'ai'

const result = streamText({
    model: yourModel,
    system: 'You are a helpful Comms assistant',
    tools: {
        fetchInbox,
        reply,
        markDone,
    },
})
```

## Features

The tools are intentionally workflow-shaped rather than 1:1 wrappers
around API endpoints, so an LLM can complete a useful action with a
small number of calls.

### Available tools

- **userInfo** — Information about the current user, including their status
- **updateUserInfo** — Change the user's name, timezone, language or status. The status is shared with Todoist (message, emoji, end, paused notifications or Karma). Over an OAuth connection this needs the `user:write` scope
- **fetchInbox** — Threads and conversations from the inbox
- **loadThread** — Load a thread with its comments
- **loadConversation** — Load a conversation with its messages
- **searchContent** — Search a workspace for threads, comments, and messages
- **getMentions** — Threads, comments, and messages mentioning the current user
- **create-channel** / **update-channel** — Create or update workspace channels through MCP
- **createThread** — Start a new channel thread. Accepts an optional `displayInInbox` boolean (default `false`). When `true`, the thread is unarchived after creation so it appears in the author's Inbox. See also [COMMS_CREATE_THREAD_DISPLAY_IN_INBOX](#environment-variables).
- **updateObject** / **deleteObject** — Edit or remove a thread, comment, or message
- **reply** — Reply to a thread or conversation
- **react** — Add a reaction to a thread, comment, conversation, or message
- **markDone** — Mark threads or conversations as read and/or archived
- **markRead** — Mark threads and/or conversations as read without archiving them (specific IDs, or everything unread in a workspace)
- **buildLink** — Build URLs to Comms resources
- **listChannels** / **getGroups** / **getUsers** / **getWorkspaces** — Discovery helpers

For details, see [src/tools](src/tools).

## Environment Variables

| Variable                               | Default      | Description                                                                                                                                                                                                                                                                                                                  |
| -------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COMMS_API_KEY`                        | _(required)_ | Your Comms API key.                                                                                                                                                                                                                                                                                                          |
| `COMMS_CREATE_THREAD_DISPLAY_IN_INBOX` | `false`      | Set to `true` to unarchive every newly-created thread so it appears in the author's Inbox, without needing to pass `displayInInbox: true` on each call. **Only takes effect when running the MCP locally.** The remote/hosted MCP does not have this variable set and will use the per-call `displayInInbox` parameter only. |

## Dependencies

- MCP server uses the official [@modelcontextprotocol/server](https://github.com/modelcontextprotocol/typescript-sdk)
- Comms TypeScript SDK [@todoist/comms-sdk](https://github.com/todoist/comms-sdk-typescript)

## Local development

### Prerequisites

- Node.js 20.18.1+
- npm
- A Comms API token

### Setup

```bash
git clone https://github.com/todoist/comms-mcp.git
cd comms-mcp
npm install
cp .env.example .env  # then add your COMMS_API_KEY
npm run build
```

### Commands

- `npm start` — Build and run the MCP inspector
- `npm run dev` — Watch mode with auto-restart
- `npm test` — Vitest
- `npm run type-check` — TypeScript
- `npm run format:check` / `npm run format:fix` — oxlint + oxfmt

### Running a single tool directly

```bash
npx tsx scripts/run-tool.ts user-info '{}'
npx tsx scripts/run-tool.ts --list
```

## Contributing

1. Tests pass (`npm test`)
2. Types pass (`npm run type-check`)
3. Lint & format pass (`npm run format:check`)

Use [Conventional Commits](https://www.conventionalcommits.org/) — `feat:`, `fix:`, `docs:`, `test:`, `chore:`.

## License

MIT