A Twist AI MCP server that lets AI agents read and act on a Twist workspace on the user's behalf.
Get current user info and manage away status (get/set/clear).
List workspaces, users, groups, and channels.
Fetch inbox data and filter by unread/archive status/date.
Load threads and conversations with comments/messages, including pagination and date filters.
Search workspace content and fetch mentions.
Create threads and direct/group conversations.
Update or delete threads, comments, and messages.
Reply to threads/conversations and add/remove emoji reactions.
Mark threads or conversations as read, archived, or done in bulk or individually.
Build valid Twist URLs for threads, comments, conversations, and messages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Twist AI MCP Server show me my inbox threads"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Library for connecting AI agents to Twist. Includes tools that can be integrated into LLMs, enabling them to access and interact with a Twist workspace on the user's behalf.
These tools can be used both through an MCP server, or imported directly in other projects to integrate them to your own AI conversational interfaces.
npm install @todoist/twist-aiPreviously published as @doist/twist-ai, which no longer receives updates. To switch, replace @doist/twist-ai with @todoist/twist-ai in your dependencies, imports and MCP client configuration.
Here's an example using Vercel's AI SDK.
import { fetchInbox, reply, markDone } from '@todoist/twist-ai'
import { streamText } from 'ai'
const result = streamText({
model: yourModel,
system: 'You are a helpful Twist assistant',
tools: {
fetchInbox,
reply,
markDone,
},
})Related MCP server: ClickUp MCP Server
You can run the MCP server directly with npx:
npx @todoist/twist-aiAdd to your Claude Desktop configuration file (claude_desktop_config.json):
{
"mcpServers": {
"twist": {
"command": "npx",
"args": ["-y", "@todoist/twist-ai"],
"env": {
"TWIST_API_KEY": "your-twist-api-key-here"
}
}
}
}Create a configuration file:
Global: ~/.cursor/mcp.json
Project-specific: .cursor/mcp.json
{
"mcpServers": {
"twist": {
"command": "npx",
"args": ["-y", "@todoist/twist-ai"],
"env": {
"TWIST_API_KEY": "your-twist-api-key-here"
}
}
}
}Then enable the server in Cursor settings if prompted.
claude mcp add twist npx @todoist/twist-aiThen set your API key:
export TWIST_API_KEY=your-twist-api-key-hereOpen Command Palette → MCP: Add Server
Configure the server:
{
"servers": {
"twist": {
"command": "npx",
"args": ["-y", "@todoist/twist-ai"],
"env": {
"TWIST_API_KEY": "your-twist-api-key-here"
}
}
}
}Create a new integration or use an existing one
Copy your API key
Add it to your MCP configuration as shown above
A key feature of this project is that tools can be reused, and are not written specifically for use in an MCP server. They can be hooked up as tools to other conversational AI interfaces (e.g. Vercel's AI SDK).
This project is in its early stages. Expect more and/or better tools soon.
Nevertheless, our goal is to provide a small set of tools that enable complete workflows, rather than just atomic actions, striking a balance between flexibility and efficiency for LLMs.
userInfo - Get information about the current user and their workspaces
fetchInbox - Fetch threads and conversations from the inbox
loadThread - Load a specific thread with its comments
loadConversation - Load a specific conversation with its messages
searchContent - Search across a workspace for threads, comments, and messages
createThread - Create a new thread in a channel. 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 TWIST_CREATE_THREAD_DISPLAY_IN_INBOX.
reply - Reply to threads or conversations
react - Add reactions to threads, comments, conversations, or messages
markDone - Mark threads or conversations as done (read and/or archived)
buildLink - Build URLs to Twist resources
For more details on each tool, see the src/tools directory.
Variable | Default | Description |
| (required) | Your Twist API key. |
|
| Set to |
MCP server using the official @modelcontextprotocol/server
Twist TypeScript SDK @todoist/twist-sdk
Node.js 18 or higher
npm
A Twist account with API access
Clone the repository:
git clone https://github.com/todoist/twist-ai.git
cd twist-aiInstall dependencies:
npm installCreate a .env file with your Twist API key:
TWIST_API_KEY=your-twist-api-key-hereBuild the project:
npm run buildnpm start - Build and run the MCP inspector for testing
npm run dev - Development mode with auto-rebuild and restart
npm test - Run all tests
npm run type-check - Run TypeScript type checking
npm run format:check - Run linting and formatting checks
npm run format:fix - Auto-fix linting and formatting issues
Contributions are welcome! Please ensure:
All tests pass (npm test)
Code is properly typed (npm run type-check)
Code passes linting and formatting checks (npm run format:check)
Use Conventional Commits for commit messages:
feat: for new features
fix: for bug fixes
docs: for documentation changes
test: for test changes
chore: for maintenance tasks
MIT
Manage the current user's away status. Supports getting, setting, and clearing away mode with types: parental, vacation, sickleave, other.
Inputs: action (required), from, type, until. Returns: type, action, isAway, awayMode
Build valid Twist URLs for threads, comments, conversations, or messages. Provide workspace_id and either (conversation_id + optional message_id) OR (thread_id + optional channel_id + optional comment_id).
Inputs: workspaceId (required), fullUrl, threadId, channelId, +3 more. Returns: url, type, params, linkType
Start a direct or group conversation with one or more users and post an initial message. Reuses the existing conversation if one already exists for the same set of users.
Inputs: content (required), recipients (required), workspaceId (required). Returns: type, content, created, success, +7 more
Create a new thread in a workspace channel. Requires a channel ID, title, and content. Optionally notify specific users or groups.
Inputs: title (required), content (required), channelId (required), groups, +2 more. Returns: type, title, groups, content, +8 more
Permanently delete a Twist object. targetType: "thread" deletes a thread (and all of its comments); "comment" deletes a single thread comment; "message" deletes a direct/group conversation message. Always pass targetId. Deletion is irreversible — confirm with the user before invoking. Note: the Twist API only allows deletion by the object's creator or a workspace admin; the call will be rejected otherwise.
Inputs: targetId (required), targetType (required). Returns: type, success, threadId, commentId, +2 more
Fetch inbox view with threads, conversations, unread counts, and unread IDs. Provides a complete picture of the inbox state. Use archiveFilter "all" to include threads marked as done alongside active threads.
Inputs: workspaceId (required), limit, sinceDate, untilDate, +2 more. Returns: type, threads, unreadCount, workspaceId, +5 more
Get groups from a workspace. Retrieves all workspace groups by default, or specific groups if groupIds array is provided. Supports optional case-insensitive search filtering by group name. Use this before passing group IDs to tools that support group notifications.
Inputs: workspaceId (required), groupIds, searchText. Returns: type, groups, totalGroups, workspaceId, +1 more
Fetch threads, comments, and messages that mention the current user. Supports filtering by channel, author, and date range. Use this instead of search-content when no keyword query is needed.
Inputs: workspaceId (required), limit, cursor, dateTo, +3 more. Returns: type, cursor, hasMore, results, +2 more
Get users from a workspace. Retrieves all workspace users by default, or specific users if userIds array is provided. Supports optional case-insensitive search filtering by name or email.
Inputs: workspaceId (required), userIds, searchText. Returns: type, users, totalUsers, workspaceId, +1 more
Get all workspaces that the user belongs to. Returns a list of workspaces with their IDs, names, creators, creation dates, and optional default channels, conversations, and plan information.
Inputs: no named parameters. Returns: type, workspaces
List channels in a workspace. By default returns only active channels; set includeArchived to true to also include archived channels. Returns channel IDs, names, descriptions, visibility (public/private), archive status, creators, creation dates, URLs, and colors.
Inputs: workspaceId (required), includeArchived. Returns: type, channels, workspaceId, totalChannels
Load a conversation (direct message) with its metadata and messages. Supports filtering by timestamp and pagination.
Inputs: conversationId (required), limit, newerThanDate, olderThanDate, +1 more. Returns: type, messages, conversation, totalMessages
Load a thread with its metadata and comments. Supports filtering by timestamp and pagination.
Inputs: threadId (required), limit, newerThanDate, olderThanDate, +1 more. Returns: type, thread, comments, totalComments
Mark threads or conversations as done. Supports individual IDs or bulk operations (mark all in workspace/channel). For threads: can mark as read, archive in inbox, or clear all unread. For conversations: can mark as read and archive.
Inputs: type (required), ids, archive, markRead, +3 more. Returns: mode, type, failed, itemType, +6 more
Add or remove an emoji reaction on a thread, comment, or conversation message. Use targetType to specify the type of object (thread, comment, or message) and targetId for the ID.
Inputs: emoji (required), targetId (required), targetType (required), operation. Returns: type, emoji, success, targetId, +3 more
Post a reply to a thread (as a comment) or conversation (as a message). Thread replies notify everyone who has interacted with the thread by default unless specific user recipients, groups, or a notifyAudience are provided.
Inputs: content (required), targetId (required), targetType (required), groups, +2 more. Returns: type, groups, content, created, +7 more
Search across a workspace for threads, comments, and messages. Supports filtering by channels, authors, dates, and mentions.
Inputs: query (required), workspaceId (required), limit, cursor, +5 more. Returns: type, query, cursor, hasMore, +3 more
Update an existing Twist object. targetType: "thread" updates a thread's title and/or body; "comment" updates a thread comment's body; "message" updates a direct/group conversation message's body. Always pass targetId. content is required for "comment" and "message"; for "thread" it is optional as long as title is provided (i.e. a thread can be renamed without re-sending the body). title is only valid when targetType is "thread".
Inputs: targetId (required), targetType (required), title, content. Returns: type, title, content, success, +10 more
Get comprehensive user information including user ID, name, email, timezone, bot status, default workspace, and away mode status.
Inputs: no named parameters. Returns: bot, name, type, email, +3 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 19 tools
Each tool targets a distinct resource or action: user self-management, workspace lookups, inbox/thread/conversation loading, search/mentions, creation, update/delete, replies, reactions, and done state. Even similar tools like get-mentions and search-content are clearly differentiated by intent.
The tool names are readable and mostly action-oriented, but retrieval verbs are inconsistent: get-workspaces, fetch-inbox, load-thread, search-content, and list-channels all describe read operations. Names like user-info and away break the verb-noun pattern entirely.
At 19 tools, the set sits in the borderline 16-25 range and feels somewhat heavy. Most tools have legitimate purposes, but a few could potentially be consolidated or omitted without losing core functionality.
The core collaboration workflows are well covered: reading inbox/threads/conversations, searching, creating threads/conversations, replying, updating/deleting objects, reacting, and marking done. Minor gaps exist around channel/workspace administration and group management, but agents can accomplish most typical tasks.
Work with shared spaces, threads, documents, skills, apps, automations, and connected tools.
Lets your assistant work with the people and agents in your Ziggs workspaces: inbox, chats, tasks.
Build and run agents and automations across hundreds of apps using natural language.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
