Zulip MCP Server — 111 tools
contains code
The Zulip DADL turns Zulip's API into an MCP server that Claude, GPT or any MCP-compatible agent can consume directly. One YAML file declares all 111 tools — user, message, realm, custom, stream, draft, and more — and ToolMesh serves them at runtime. No Python boilerplate, no per-endpoint code, no separate MCP server process.
Below: the endpoint coverage matrix, a two-block ToolMesh setup, the full tool reference grouped by Zulip feature area, required credential scopes.
Source: Zulip REST API
Which Zulip endpoints are covered?
67% (111 of ~165 endpoints)
Focus: messages (send + get + get-one + update + delete + render + history + reactions + flags + flags-for-narrow + mark-as-read + read-receipts + typing + matches-narrow), channels/streams (list + get-by-id + get-id-by-name + update + archive + topics + subscribers + delete-topic + subscription-status + email-address), subscriptions (list + subscribe-or-create + unsubscribe + update-settings), users (list + get + by-email + own + create + update + deactivate + reactivate + presence + status + regenerate-own-api-key + update-own-settings), user groups (list + create + update + deactivate + members + subgroups), personal preferences (mute/unmute user, topic visibility policy follow/mute/unmute, alert words CRUD), drafts (CRUD), saved snippets (CRUD), scheduled messages (CRUD), real-time events (register + get + delete), invitations (send + list + resend + revoke + multi-use), attachments (list + delete), files (upload + custom emoji upload), org admin (update_realm + user_settings_defaults + linkifiers full CRUD + reorder + custom profile fields full CRUD + reorder + code playgrounds + realm domains + default streams + bot CRUD + regenerate bot api key), server/realm (server settings + linkifiers list + custom emoji list + deactivate)
Missing: OAuth/SAML/external auth flows, mobile push device registration (APNS/FCM tokens), email confirmation flows, password reset flows, video call provider connection setup (the realm setting is covered, the per-call plumbing isn't), navigation views, message reminders (3 endpoints), realm export/import requests, SCIM provisioning, in-app hotspots & tutorial step tracking, BotConfig per-bot key-value storage (3 endpoints), some dev-only endpoints, billing/plan management
How do you configure the Zulip DADL?
- Decide whether you want to use a human user account or a dedicated bot (recommended for production).
- For a bot: log into Zulip → click your avatar → Personal Settings → Bots → Add a new bot.
- Choose type 'Generic bot' (most flexible). Give it a name and email. Click Create.
- Click the download icon next to the new bot to view its API key, or click the copy icon.
- For a human account: Personal Settings → Account & privacy → API key → Manage your API key → enter your password → copy the key.
- Store BOTH the email address and the API key — they are used together as HTTP Basic credentials.
- Subscribe the bot to any channels it needs to read or post in (channels → settings → Add subscribers).
- Note your organization URL: https://YOUR-ORG.zulipchat.com (Zulip Cloud) or your self-hosted domain.
- Set BOTH env vars in your ToolMesh deployment:
- CREDENTIAL_ZULIP_EMAIL=<bot or user email address> (used as HTTP Basic username)
- CREDENTIAL_ZULIP_API_KEY=<api key> (used as HTTP Basic password)
Environment variable: CREDENTIAL_ZULIP_API_KEY
Two credentials are needed: zulip_email (the bot's or user's email) and zulip_api_key (the API key string). Both are sent as HTTP Basic auth — ToolMesh handles the base64 encoding. The url in backends.yaml is the bare org URL WITHOUT the /api/v1 suffix (the DADL adds it). For Zulip Cloud orgs the URL pattern is https://<slug>.zulipchat.com; for self-hosted it is whatever the admin configured. Anyone with the API key can impersonate the bot — treat it as a secret.
How do you install the Zulip MCP server with ToolMesh?
Add to your backends.yaml:
- name: zulip
transport: rest
dadl: zulip.dadl
url: "https://your-org.zulipchat.com"
Set the credential:
CREDENTIAL_ZULIP_API_KEY=your-token-hereWhat 111 tools does the Zulip DADL expose?
POSTsend_messageSend a message to a channel topic or as a direct message. For channel messages set type=channel (or 'stream'), to=<channel name or stream_id>, topic=<topic name>, content=<markdown>. For DMs set type=direct (or 'private'), to=<user email/id or JSON array of user IDs>, content=<markdown>. Returns {id, automatic_new_visibility_policy?}.
GETget_messagesFetch a range of messages around an anchor. Use anchor + num_before + num_after to page; anchor can be a message ID or one of: 'newest', 'oldest', 'first_unread'. narrow is a JSON-encoded array of filter objects, e.g. '[{"operator":"channel","operand":"general"},{"operator":"topic","operand":"deploys"}]'. Operators: channel, topic, sender, search, is, has, dm, dm-including, id, with. Max 5000 messages per request (recommend ≤1000). Response includes {messages, anchor, found_oldest, found_newest, found_anchor, history_limited}.
GETget_messageFetch a single message by ID. Returns the message object with content, sender info, topic, channel, reactions, flags, and timestamps.PATCHupdate_messageEdit a message's content, topic, or move it to a different channel. propagate_mode controls scope: change_one (default, this message), change_later (this + later in same topic), change_all (entire topic). Only the sender or users with appropriate permissions can edit.
DELETEdelete_messagePermanently delete a message. Only the sender (within edit window) or organization administrators can delete. Cannot be undone.POSTrender_messageRender a Markdown string to HTML using Zulip-flavored Markdown, without sending it. Useful for previewing how a message will look.GETget_message_historyGet the edit history of a message. Returns array of snapshots (oldest first) including topic, content, rendered_content, timestamp, user_id, and prev_* fields where changed.POSTadd_reactionAdd an emoji reaction to a message. emoji_name is the Zulip emoji name (e.g. 'thumbs_up', 'octopus').DELETEremove_reactionRemove your own emoji reaction from a message.POSTupdate_message_flagsAdd or remove a flag on a batch of messages by ID. Flags: read, starred, collapsed. Some flags are read-only and change automatically (mentioned, has_alert_word, etc.). op is 'add' or 'remove'.
POSTupdate_message_flags_for_narrowAdd or remove a flag across all messages matching a narrow. Useful for 'mark all unread in this channel as read'. anchor + num_before + num_after define the scope (same semantics as get_messages). Returns processed_count, updated_count, first/last_processed_id, found_oldest/found_newest.
POSTmark_all_as_readMark every unread message visible to the current user as read. Deprecated — prefer update_message_flags_for_narrow with anchor=oldest, num_after=large.POSTmark_stream_as_readMark all unread messages in a channel as read. Deprecated — prefer update_message_flags_for_narrow with a channel narrow.POSTmark_topic_as_readMark all unread messages in a topic as read. Deprecated — prefer update_message_flags_for_narrow with channel + topic narrow.GETget_read_receiptsGet the list of user IDs who have read a message. Excludes the sender, users with send_read_receipts disabled, and muted users.POSTset_typing_statusSend a "user is typing" notification. Clients call this every few seconds while typing, then send op=stop when done. type=direct needs `to` (JSON array of user IDs); type=channel needs stream_id + topic.
GETcheck_messages_match_narrowTest which of a given set of message IDs match a narrow. Useful for selectively highlighting search hits in a list. Returns a dict keyed by message ID with match_content + match_subject (HTML, with search keyword highlighting). Messages that don't match are omitted.
GETget_streamsList channels visible to the authenticated user. Filters control which categories are included (public, subscribed, default, archived). Returns array of stream objects with stream_id, name, description, invite_only, is_web_public, history_public_to_subscribers, message_retention_days, and permission groups.
GETget_streamGet full details of a channel by its numeric ID. Returns stream object with name, description, privacy, retention, permission groups, subscriber_count, stream_weekly_traffic.GETget_stream_idLook up a channel's numeric ID by its exact name. Returns {stream_id}. Returns code=BAD_REQUEST if the channel does not exist or is not accessible.PATCHupdate_streamUpdate a channel's settings. Requires channel admin permission. All body params optional — only fields you pass are changed. Permission group settings take a JSON-encoded object like {"new":"role:everyone"} or a group ID.
DELETEarchive_streamArchive (delete) a channel. Messages remain in the database but the channel is hidden. Organization admins can unarchive via update_stream. Irreversible from the API side without admin recovery.GETget_stream_topicsList topics in a channel, ordered by recency (most recent first). Returns array of {name, max_id (last message ID)}. The user must have access to the channel.GETget_subscribersList user IDs subscribed to a channel. Returns array of integers.POSTdelete_topicDelete an entire topic and all its messages. Admin-only. Processes in batches — the response contains 'complete' (boolean); if false, RETRY the same call until complete=true.
GETget_subscription_statusCheck whether a specific user is subscribed to a specific channel. Returns {is_subscribed}.GETget_stream_email_addressGet the email address that, when emailed, posts to a channel. Used for email integrations.GETget_subscriptionsList channels the current user/bot is subscribed to, with all subscription-specific settings (notifications, color, pin, mute). include_subscribers='partial' returns subscribers only for bots and recently-active users (faster for big orgs).
POSTcreate_or_subscribeSubscribe one or more users to one or more channels. CREATES channels that don't yet exist (this is the only way to create a channel via the API). principals is a JSON array of user IDs or emails — omit to subscribe yourself.
DELETEunsubscribeUnsubscribe one or more users from channels. principals defaults to the current user. Cannot remove admins from public channels they administer.POSTupdate_subscription_settingsUpdate per-channel subscription preferences (color, pin_to_top, audible_notifications, desktop_notifications, push_notifications, email_notifications, is_muted, in_home_view). subscription_data is a JSON array of {stream_id, property, value} objects.
GETget_usersList all users in the organization. Returns array of user objects with id, email, full_name, is_bot, is_active, role, avatar_url, timezone, date_joined.GETget_userGet one user by numeric ID. Preferred over get_user_by_email because email can change.GETget_user_by_emailGet one user by email address. Email can be the real address or the dummy user{id}@{host} form.GETget_own_userGet the currently authenticated user (or bot). Returns identity, role, custom profile data, and account flags. The simplest test that auth is configured correctly.POSTcreate_userCreate a new user. Admin-only. The new user receives an email to set their password unless full_name and password are pre-set.PATCHupdate_userUpdate a user's profile or role. Admins can change role and custom fields; users can update their own profile via this endpoint too (some fields).DELETEdeactivate_userDeactivate a user. They can no longer log in or use the API. Their messages remain. Reversible via reactivate_user.POSTreactivate_userReactivate a previously deactivated user. Admin only.GETget_user_presenceGet a single user's current presence (active/idle, last update timestamp). Path accepts either user ID or email.GETget_realm_presenceGet presence for all users the current user can access. Returns server_timestamp and presences keyed by email.POSTupdate_presenceUpdate the current user's presence (active/idle/offline). Most clients call this every minute while open.GETget_user_statusGet a user's custom status (status_text, emoji, away flag).POSTupdate_statusSet your own custom status — a short text + optional emoji. Pass empty status_text to clear.POSTregenerate_own_api_keyGenerate a new API key for the authenticated user. Returns {api_key}. WARNING: the old key stops working immediately and all devices using it (including this connection) must be re-authenticated. Use sparingly.
PATCHupdate_own_settingsUpdate the authenticated user's own preferences (display, notifications, behavior, privacy). Pass only the fields you want to change. Admins can also use target_users to bulk-update settings for others (Zulip 12.0+).
GETget_user_groupsList all user groups in the organization. Returns array of group objects with id, name, description, members (user IDs), direct_subgroup_ids, deactivated.POSTcreate_user_groupCreate a new user group with an initial set of members. can_*_group fields accept a JSON-encoded group ID or 'role:everyone'/'role:members' etc.PATCHupdate_user_groupUpdate a user group's name, description, or permission settings. Admin-only or has_manage permission.DELETEdeactivate_user_groupDeactivate (soft-delete) a user group. The group remains in the database but is hidden. Cannot deactivate system groups.POSTupdate_user_group_membersAdd or remove members from a user group. Pass JSON arrays of user IDs for 'add' and 'delete'.POSTupdate_user_group_subgroupsAdd or remove nested subgroups from a user group. Pass JSON arrays of group IDs.GETget_user_group_membersList all member user IDs of a group. Set direct_member_only=true to exclude transitively-included members from subgroups.POSTmute_userMute another user from the current user's perspective. Messages sent by muted users are automatically marked as read and hidden in the UI. Mute state is per-user — only affects the calling account. There is no dedicated "list muted users" endpoint; the current list is delivered via the muted_users key in register_queue fetch.
DELETEunmute_userUnmute a previously muted user. Returns an error if the user is not currently muted.POSTupdate_user_topic_visibilitySet the current user's visibility policy for a specific channel + topic. This is the modern replacement for the deprecated /users/me/subscriptions/muted_topics endpoint. Supports both muting (hide notifications) and following (boost notifications), plus unmute and reset.
GETget_alert_wordsGet the current user's configured alert words. Alert words trigger a notification when they appear in any message visible to the user. Case-insensitive, max 100 chars per word.
POSTadd_alert_wordsAdd one or more alert words. alert_words is a JSON-encoded array of strings, e.g. '["deploy","incident"]'.DELETEremove_alert_wordsRemove one or more alert words. alert_words is a JSON-encoded array of strings to remove. Returns the remaining alert words.GETget_draftsGet all drafts saved by the current user (ordered by most recently edited).POSTcreate_draftsCreate one or more drafts. drafts is a JSON array of draft objects: {type, to, topic, content, timestamp}.PATCHedit_draftReplace an existing draft's contents.DELETEdelete_draftDelete a draft permanently.GETget_saved_snippetsList the current user's saved snippets — reusable text fragments (e.g. canned responses, command incantations, KB-style notes). Returns array of {id, title, content, date_created}.POSTcreate_saved_snippetCreate a saved snippet. Returns {saved_snippet_id}.PATCHedit_saved_snippetEdit a saved snippet's title or content.DELETEdelete_saved_snippetPermanently delete a saved snippet.GETget_scheduled_messagesList the current user's pending scheduled messages, ordered by delivery time.POSTcreate_scheduled_messageSchedule a message for later delivery. scheduled_delivery_timestamp is a UNIX timestamp in UTC seconds.PATCHupdate_scheduled_messageUpdate a pending scheduled message. Can change content, topic, recipients, or scheduled time. Pass only the fields you want to change.DELETEdelete_scheduled_messageCancel a pending scheduled message before it is delivered.POSTregister_queueRegister an event queue and fetch initial state. The server returns queue_id, last_event_id, and snapshots of requested data. Use get_events to long-poll for new events. Always call delete_queue when finished — queues consume server resources. event_types and fetch_event_types are JSON-encoded arrays of strings.
GETget_eventsLong-poll for new events on a registered queue. queue_id from register_queue. last_event_id is the highest event ID already processed (-1 for first call). dont_block=true returns immediately (possibly with empty events). Default behavior blocks up to ~10 minutes.
DELETEdelete_queueDelete a previously registered event queue. Always call this when done with register_queue to free server resources.POSTsend_invitesSend email invitations to join the organization. invite_as: 100=owner, 200=admin, 300=moderator, 400=member (default), 600=guest. stream_ids is a JSON array of channels to auto-subscribe. Requires admin role typically.
POSTcreate_multi_use_invite_linkCreate a reusable invite link that anyone can use to join the org. Returns {invite_link}.GETlist_invitesList pending email and multi-use invitations.POSTresend_inviteResend the invitation email for a pending email invitation.DELETErevoke_inviteRevoke a pending email invitation.DELETErevoke_multi_use_inviteRevoke a multi-use invite link.POSTupload_fileUpload a file. Pass file as a file_url — ToolMesh will fetch and forward it as multipart. Response includes a relative url like /user_uploads/1/4e/.../filename. To share, embed in a message as [name](url). For files >25MB use the tus resumable upload endpoint (not modeled).
GETget_attachmentsList the current user's uploaded attachments. Returns {attachments: [...], upload_space_used}.DELETEdelete_attachmentDelete an uploaded attachment by ID. The file is removed from storage; messages referencing it will show a broken link.GETget_server_settingsGet public server configuration including zulip_version, zulip_feature_level, available auth methods, and realm branding. Works WITHOUT authentication — useful for discovery.GETget_realm_linkifiersList linkifiers (regex → URL template rules) configured for the realm. Clients should process them in order. Returns array of {pattern, url_template, id, example_input, ...}.GETget_custom_emojiGet all custom emoji defined in the realm. Returns map of emoji_id → {id, name, source_url, still_url, deactivated, author_id}.DELETEdeactivate_custom_emojiDeactivate (hide) a realm custom emoji. The image data remains but the emoji is no longer selectable.POSTupload_custom_emojiUpload a new custom emoji to the realm. emoji_name allows letters/digits/dashes/spaces. File goes in the request body as form data. Server limits file size (default 5 MB) and accepts common image/gif formats.
PATCHupdate_realmUpdate org-wide (realm) settings. Admin/owner only. Only fields you pass are changed. Setting target_users on the related update_own_settings is for per-user defaults; this endpoint changes org-wide policy. The full realm settings surface is ~80 fields; the most commonly-tuned ones are exposed here. For uncommon fields, pass via this same endpoint.
PATCHupdate_realm_user_settings_defaultsUpdate the default per-user settings applied to newly-created accounts in the realm. Does NOT change settings of existing users. Admin/owner only.
POSTadd_linkifierAdd a new linkifier (regex → URL template). Used to auto-link ticket IDs like 'JIRA-1234', commit hashes, internal references, etc. url_template uses RFC 6570 with named variables captured from the regex (e.g. '{ticket_id}').
PATCHupdate_linkifierUpdate an existing linkifier's pattern, template, or auxiliary fields. Pass only fields to change.DELETEremove_linkifierDelete a linkifier. Existing messages keep their rendered links but new messages won't auto-link this pattern.PATCHreorder_linkifiersReorder linkifiers. Order matters when patterns overlap — earlier wins. Pass a JSON array of all linkifier IDs in the desired order.
GETget_custom_profile_fieldsList custom profile fields configured for the realm. Returns array of {id, type, name, hint, field_data, order, ...}. Field types: 1=short text, 2=paragraph, 3=dropdown, 4=date, 5=link, 6=users, 7=external account, 8=pronouns.
POSTcreate_custom_profile_fieldCreate a new custom profile field that users can fill in their profile. field_data is type-specific JSON (e.g. choices for dropdown).PATCHupdate_custom_profile_fieldUpdate a custom profile field. Cannot change field_type after creation.DELETEdelete_custom_profile_fieldDelete a custom profile field. All user values for this field are lost. Cannot be undone.PATCHreorder_custom_profile_fieldsReorder custom profile fields. Pass a JSON array of field IDs in the desired display order.POSTadd_realm_playgroundAdd a code playground integration — clicking the "View in playground" button on a code block of the matching language opens the code in an external editor (e.g. play.rust-lang.org). url_template must contain exactly one `{code}` variable.
DELETEremove_realm_playgroundRemove a code playground integration.POSTadd_realm_domainAdd an email domain to the org's allowed-signup list (only effective when realm setting emails_restricted_to_domains=true). Use to lock self-signup to your company domain.
PATCHupdate_realm_domainToggle allow_subdomains on an existing realm domain entry.DELETEremove_realm_domainRemove an email domain from the allowed-signup list.POSTadd_default_streamMark a channel as a default channel — new users are auto-subscribed on signup (unless include_realm_default_subscriptions is overridden in the invite).
DELETEremove_default_streamRemove a channel from the realm's default channel list. Existing subscribers are not affected.GETget_botsList bots owned by the current user. Returns array of {user_id, username, full_name, api_key, default_sending_stream, default_events_register_stream, default_all_public_streams, avatar_url, services}. IMPORTANT: this endpoint and the other /bots endpoints are for HUMAN accounts only — bot accounts cannot list/manage other bots (Zulip returns 'This endpoint does not accept bot requests'). Connect with a human user's API key to manage bots.
POSTcreate_botCreate a new bot owned by the current user. bot_type: 1=Generic, 2=Incoming webhook, 3=Outgoing webhook, 4=Embedded. Generic is the most flexible.
PATCHupdate_botUpdate settings of a bot owned by the current user (or any bot, for admins).POSTregenerate_bot_api_keyGenerate a new API key for one of your bots. Old key stops working immediately.DELETEdeactivate_botDeactivate (delete) a bot owned by the current user. Reversible by re-activating the bot user.What composite workflows does the Zulip DADL provide? ⚠ contains code
FNsend_channel_messageConvenience wrapper around send_message for the common case of posting to a channel topic. Pass channel_name OR stream_id (one is required) plus topic and content.
FNsearch_messagesSearch for messages by free-text query, optionally within a channel and/or topic. Returns up to `limit` matching messages, newest first. Wraps get_messages with a constructed narrow.
FNget_recent_in_topicGet the N most recent messages in a specific channel + topic. Convenience wrapper around get_messages with a channel+topic narrow anchored at 'newest'.
FNmark_all_in_channel_readMark every unread message in a channel as read (preferred replacement for mark_stream_as_read).FNsearch_usersFind users by a prefix match on full_name or email (Zulip has no dedicated user-search endpoint, so this fetches the org user list and filters client-side). Bots and inactive users are excluded by default.
FNdaily_summaryBuild a digest of unread message activity for the authenticated user — total unread count, breakdown by channel, top topics, and DM senders. Uses get_messages with an is:unread narrow; for very busy accounts, raise `max_scan` (Zulip caps at 5000 per request).