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 the tools

1. Install

npm install @doist/comms-mcp

2. Plug them into an AI

Example with Vercel's AI SDK:

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

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

Using as an MCP server

Quick start

npx @doist/comms-mcp

Setup

Claude Desktop

Add to claude_desktop_config.json:

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

Cursor

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

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

Claude Code (CLI)

claude mcp add comms npx @doist/comms-mcp
export COMMS_API_KEY=your-comms-api-key-here

Visual Studio Code

1. Command Palette → MCP: Add Server
2. Configure:

{
    "servers": {
        "comms": {
            "command": "npx",
            "args": ["-y", "@doist/comms-mcp"],
            "env": {
                "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:

"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.

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.
• 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.

Environment Variables

Dependencies

• MCP server uses the official @modelcontextprotocol/server
• Comms TypeScript SDK @doist/comms-sdk

Local development

Prerequisites

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

Setup

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

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 — feat:, fix:, docs:, test:, chore:.

License

MIT