twist-ai
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 Show my inbox threads and any replies needed"
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.
Twist AI and MCP SDK
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.
Using tools
1. Add this repository as a dependency
npm install @doist/twist-ai2. Import the tools and plug them to an AI
Here's an example using Vercel's AI SDK.
import { fetchInbox, reply, markDone } from '@doist/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: slack-mcp-server
Using as an MCP server
Quick Start
You can run the MCP server directly with npx:
npx @doist/twist-aiSetup Guide
Claude Desktop
Add to your Claude Desktop configuration file (claude_desktop_config.json):
{
"mcpServers": {
"twist": {
"command": "npx",
"args": ["-y", "@doist/twist-ai"],
"env": {
"TWIST_API_KEY": "your-twist-api-key-here"
}
}
}
}Cursor
Create a configuration file:
Global:
~/.cursor/mcp.jsonProject-specific:
.cursor/mcp.json
{
"mcpServers": {
"twist": {
"command": "npx",
"args": ["-y", "@doist/twist-ai"],
"env": {
"TWIST_API_KEY": "your-twist-api-key-here"
}
}
}
}Then enable the server in Cursor settings if prompted.
Claude Code (CLI)
claude mcp add twist npx @doist/twist-aiThen set your API key:
export TWIST_API_KEY=your-twist-api-key-hereVisual Studio Code
Open Command Palette → MCP: Add Server
Configure the server:
{
"servers": {
"twist": {
"command": "npx",
"args": ["-y", "@doist/twist-ai"],
"env": {
"TWIST_API_KEY": "your-twist-api-key-here"
}
}
}
}Getting your Twist API Key
Create a new integration or use an existing one
Copy your API key
Add it to your MCP configuration as shown above
Features
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.
Available Tools
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
displayInInboxboolean (defaultfalse). Whentrue, 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.
Environment Variables
Variable | Default | Description |
| (required) | Your Twist API key. |
|
| Set to |
Dependencies
MCP server using the official @modelcontextprotocol/server
Twist TypeScript SDK @doist/twist-sdk
Local Development Setup
Prerequisites
Node.js 18 or higher
npm
A Twist account with API access
Setup
Clone the repository:
git clone https://github.com/doist/twist-ai.git
cd twist-aiInstall dependencies:
npm installCreate a
.envfile with your Twist API key:
TWIST_API_KEY=your-twist-api-key-hereBuild the project:
npm run buildDevelopment Commands
npm start- Build and run the MCP inspector for testingnpm run dev- Development mode with auto-rebuild and restartnpm test- Run all testsnpm run type-check- Run TypeScript type checkingnpm run format:check- Run linting and formatting checksnpm run format:fix- Auto-fix linting and formatting issues
Contributing
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 featuresfix:for bug fixesdocs:for documentation changestest:for test changeschore:for maintenance tasks
License
MIT
Available Tools
19 toolsawayAIdempotent
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-linkARead-onlyIdempotent
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
create-conversationA
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-threadB
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
delete-objectADestructiveIdempotent
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-inboxARead-onlyIdempotent
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-groupsARead-onlyIdempotent
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
get-mentionsARead-onlyIdempotent
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-usersARead-onlyIdempotent
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-workspacesARead-onlyIdempotent
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-channelsARead-onlyIdempotent
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-conversationARead-onlyIdempotent
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-threadBRead-onlyIdempotent
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-doneADestructiveIdempotent
Mark threads or conversations as read/unread and archived/unarchived. Individual IDs take priority over bulk selectors whenever both are provided. For threads: markRead=false marks unread, archive=false unarchives; bulk operations (workspaceId/channelId, only used when no ids are given) can also 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
reactADestructive
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
replyA
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-contentARead-onlyIdempotent
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-objectAIdempotent
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
user-infoARead-onlyIdempotent
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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Tools are mostly distinct with clear scopes: load-thread vs load-conversation vs fetch-inbox vs search-content vs get-mentions all retrieve content but with specific purposes. The generic update-object and delete-object use targetType to differentiate, reducing ambiguity. Only slight overlap between get-users and user-info, but their purposes are different enough.
Naming follows a consistent kebab-case, verb-first pattern (e.g., get-users, load-thread, create-thread, mark-done). A few single-word verbs like reply, react, and away deviate from the compound style but still follow a verb-based convention. Overall, naming is predictable and consistent.
With 19 tools, the set is substantial but appropriate for a full-featured messaging platform API. Each tool addresses a distinct aspect (workspaces, channels, threads, conversations, reactions, search, etc.), and while a few are auxiliary (build-link), the count feels well-scoped for the domain.
The tool set covers core operations for threads, conversations, messages, reactions, user management, and search. However, there is no direct tool for creating or deleting channels, and no way to list threads in a channel without using search or inbox. Updating a conversation is also unsupported (update-object only handles threads, comments, and messages). These are notable gaps for complete lifecycle management.
Maintenance
Related MCP Connectors
Work with shared spaces, threads, documents, skills, apps, automations, and connected tools.
Start TODOs, send follow-ups and read agent results in your TODO for AI workspace.
Lets your assistant work with the people and agents in your Ziggs workspaces: inbox, chats, tasks.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Related MCP Servers
AlicenseBqualityAmaintenanceEnables AI agents to access and modify Todoist accounts to manage tasks and projects on the user's behalf. It provides a suite of tools for task operations and supports interactive UI widgets for a rich visual experience in AI chat interfaces.49565MIT- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Slack workspaces, including listing channels, posting messages, replying to threads, adding reactions, and retrieving user information.1020 npmMIT

Twist AI MCP Serverofficial
AlicenseAqualityBmaintenanceEnables AI agents to access and interact with a Twist workspace, managing threads, conversations, inbox, and more through natural language.193MIT- AlicenseBqualityBmaintenanceEnables AI assistants to interact with Slack workspaces, providing tools for reading messages, posting content, managing channels, and more.2244MIT