Navigation: Home

API Reference

Complete documentation for all 25 tools and 4 resources available in the Zulip MCP Server.

Resources (4 available)
Helper Tools (2 tools)
Message Operations (10 tools)
User Operations (5 tools)
Stream Management (4 tools)
Drafts & Files (4 tools)

Resources

Resources provide contextual data to enhance LLM understanding of your Zulip workspace.

1. User Directory

URI: zulip://users?include_bots={include_bots}

Browse organization members with roles and status information.

Parameters:

include_bots (boolean, optional): Include bot users in results

Returns: Complete user directory with:

User IDs, emails, and full names
Role information (owner, admin, moderator, guest, member)
Activity status and bot indicators

2. Streams Directory

URI: zulip://streams?include_archived={include_archived}

Explore available streams and their settings.

Parameters:

include_archived (boolean, optional): Include archived streams

Returns: Stream information including:

Stream IDs, names, and descriptions
Privacy settings (invite-only, web-public)
Archive status and announcement-only flags

3. Message Formatting Guide

URI: zulip://formatting/guide

Complete Zulip markdown syntax reference for message formatting.

Returns: Comprehensive formatting guide covering:

Standard Markdown (bold, italic, code, links)
Zulip-specific features (mentions, stream links, spoilers)
Code blocks with syntax highlighting
Math expressions and custom emoji

4. Common Patterns

URI: zulip://patterns/common

LLM usage workflows and troubleshooting guidance.

Returns: Best practices including:

Recommended tool workflows
Common mistakes to avoid
Debugging tips and error resolution
Tool selection guidance

Helper Tools

LLM-optimized tools for discovery and orientation.

1. search-users

🔍 DISCOVERY: Search for users by partial name or email when you don’t know exact details.

Parameters:

query (string, required): Name, email, or partial match to search for users
limit (number, optional): Maximum number of results to return (default: 10)

Returns: Array of matching users with basic info (name, email, ID, status)

Example:

{
  "query": "john",
  "limit": 5
}

2. get-started

🚀 START HERE: Test connection and get workspace overview. Perfect for orientation and troubleshooting.

Parameters: None

Returns: Connection status and workspace information:

Your email and Zulip URL
Available streams count and sample names
Recent activity indicators
Quick tips for LLM usage

Message Operations

Comprehensive message management capabilities.

1. send-message

💬 SEND MESSAGE: Send messages to streams or direct users.

Parameters:

type (enum, required): “stream” for channels, “direct” for private messages
to (string, required): For streams: channel name. For direct: comma-separated emails
content (string, required): Message content using Zulip Markdown syntax
topic (string, optional): Topic name for stream messages (required for streams)

Example - Stream Message:

{
  "type": "stream",
  "to": "general",
  "topic": "Daily Standup",
  "content": "Good morning team! 👋\n\n**Today's Goals:**\n- Review PR #123\n- Deploy feature X"
}

Example - Direct Message:

{
  "type": "direct",
  "to": "user@example.com,colleague@example.com",
  "content": "Can you review the latest changes when you have a moment?"
}

2. get-messages

📋 BULK RETRIEVAL: Get multiple messages with filtering, pagination, and search.

Parameters:

anchor (number string, optional): Starting point: message ID, “newest”, “oldest”, or “first_unread”
num_before (number, optional): Number of messages before anchor (max 1000)
num_after (number, optional): Number of messages after anchor (max 1000)
narrow (array, optional): Filters: [["stream", "name"], ["topic", "name"], ["sender", "email"], ["search", "query"]]
message_id (number, optional): Get specific message by ID

Example - Stream History:

{
  "narrow": [["stream", "general"], ["topic", "announcements"]],
  "num_before": 50
}

Example - Search Messages:

{
  "narrow": [["search", "deployment"], ["sender", "admin@example.com"]]
}

3. get-message

🔍 SINGLE MESSAGE: Get complete details about one specific message.

Parameters:

message_id (number, required): Unique message ID to retrieve
apply_markdown (boolean, optional): Return HTML content (true) or raw Markdown (false). Default: true
allow_empty_topic_name (boolean, optional): Allow empty topic names in response. Default: false

Returns: Single message with full details including edit history and reactions.

4. edit-message

Edit an existing message’s content or topic.

Parameters:

message_id (number, required): Unique ID of the message to edit
content (string, optional): New message content with Markdown formatting
topic (string, optional): New topic name (for stream messages only)

5. delete-message

Delete a message by its ID.

Parameters:

message_id (number, required): Unique ID of the message to delete

6. add-emoji-reaction

Add an emoji reaction to a message.

Parameters:

message_id (number, required): ID of the message to react to
emoji_name (string, required): Emoji name (e.g., “thumbs_up”, “heart”, “rocket”)
emoji_code (string, optional): Unicode code point for the emoji
reaction_type (enum, optional): “unicode_emoji”, “realm_emoji”, or “zulip_extra_emoji”

7. remove-emoji-reaction

Remove an emoji reaction from a message.

Parameters:

message_id (number, required): ID of the message to remove reaction from
emoji_name (string, required): Emoji name to remove
emoji_code (string, optional): Unicode code point for the emoji
reaction_type (enum, optional): Type of emoji reaction

8. upload-file

Upload a file or image to Zulip.

Parameters:

filename (string, required): Name of the file including extension
content (string, required): Base64 encoded file content
content_type (string, optional): MIME type. Auto-detected if not provided

Returns: File URI for use in messages

9. get-message-read-receipts

Get list of users who have read a specific message.

Parameters:

message_id (number, required): Unique message ID to get read receipts for

Returns: Array of user IDs who have read the message

10. create-scheduled-message

Schedule a message to be sent at a future time.

Parameters:

type (enum, required): “stream” for channels, “direct” for private messages
to (string, required): Recipients (channel name or comma-separated emails)
content (string, required): Message content with Markdown formatting
topic (string, optional): Topic for stream messages
scheduled_delivery_timestamp (number, required): Unix timestamp when message should be sent

User Operations

User discovery and profile management.

1. get-users

👥 ALL USERS: Get complete list of all users in the organization.

Parameters:

client_gravatar (boolean, optional): Include Gravatar URLs for users. Default: true
include_custom_profile_fields (boolean, optional): Include custom profile fields. Default: false

Returns: Complete user list with profiles, roles, and activity status

2. get-user-by-email

📧 EXACT LOOKUP: Find a user when you have their exact email address.

Parameters:

email (string, required): Email address of the user to look up
client_gravatar (boolean, optional): Include Gravatar profile image URL
include_custom_profile_fields (boolean, optional): Include organization-specific custom profile fields

Returns: Single user with complete profile details

3. get-user

🆔 DETAILED LOOKUP: Get comprehensive user profile when you have their user ID.

Parameters:

user_id (number, required): Unique user ID to retrieve information for
client_gravatar (boolean, optional): Include Gravatar URL. Default: true
include_custom_profile_fields (boolean, optional): Include custom profile fields. Default: false

Returns: Complete user information including role, timezone, avatar, and custom fields

4. update-status

Update user status message with emoji and availability.

Parameters:

status_text (string, optional): Status message text (max 60 chars, empty string clears status)
away (boolean, optional): Set away status (deprecated in Zulip 6.0)
emoji_name (string, optional): Emoji name for status
emoji_code (string, optional): Emoji identifier
reaction_type (enum, optional): “unicode_emoji”, “realm_emoji”, or “zulip_extra_emoji”

Examples:

{
  "status_text": "In a meeting",
  "emoji_name": "coffee",
  "emoji_code": "2615",
  "reaction_type": "unicode_emoji"
}

5. get-user-groups

Get all user groups in the organization.

Parameters: None

Returns: List of user groups with member counts and descriptions

Stream Management

Stream (channel) discovery and management.

1. get-subscribed-streams

📺 USER STREAMS: Get all streams you’re subscribed to.

Parameters:

include_subscribers (boolean, optional): Include subscriber lists for streams

Returns: Your stream subscriptions with settings and permissions

2. get-stream-id

🔢 STREAM ID LOOKUP: Get the numeric ID of a stream when you know its name.

Parameters:

stream_name (string, required): Name of the stream to get ID for

Returns: Stream ID for the specified stream name

3. get-stream-by-id

📊 STREAM DETAILS: Get comprehensive information about a stream when you have its numeric ID.

Parameters:

stream_id (number, required): Unique stream ID to get details for
include_subscribers (boolean, optional): Include subscriber list

Returns: Complete stream information including settings, description, and creation date

4. get-topics-in-stream

💬 STREAM TOPICS: Get all recent topics (conversation threads) in a specific stream.

Parameters:

stream_id (number, required): Unique stream ID to get topics for

Returns: List of recent topics with their latest message IDs

Drafts & Files

Message draft management and file operations.

1. create-draft

📝 CREATE DRAFT: Save a message as draft for later editing or sending.

Parameters:

type (enum, required): “stream” for channels, “private” for direct messages
to (array, required): Array of user IDs for private messages, or single channel ID for stream messages
topic (string, required): Topic for stream messages (required even for private messages in API)
content (string, required): Draft message content with Markdown formatting
timestamp (number, optional): Unix timestamp for draft creation (defaults to current time)

2. get-drafts

Retrieve all saved message drafts.

Parameters: None

Returns: Array of all saved drafts with content and metadata

3. edit-draft

Update an existing message draft.

Parameters:

draft_id (number, required): Unique draft ID to edit
type (enum, required): Draft message type
to (array, required): Array of user IDs or channel ID
topic (string, required): Topic for the draft
content (string, required): Draft content
timestamp (number, optional): Updated timestamp

4. edit-scheduled-message

Modify a scheduled message before it’s sent.

Parameters:

scheduled_message_id (number, required): Unique scheduled message ID to edit
type (enum, optional): Message type
to (string, optional): Recipients (channel name or comma-separated emails)
content (string, optional): New message content
topic (string, optional): New topic for stream messages
scheduled_delivery_timestamp (number, optional): New delivery timestamp

Tool Selection Guide

When to use each user tool:

🔍 search-users → Exploring, don’t know exact details, want multiple options
📧 get-user-by-email → Have exact email, need profile information
🆔 get-user → Have user ID from search results, need complete details

When to use each message tool:

📋 get-messages → Browse conversations, search content, get message history
🔍 get-message → Analyze one specific message, check reactions/edit history

Recommended Workflows:

Discovery: get-started → search-users → send-message
User Lookup: search-users (explore) → get-user-by-email (exact) → get-user (detailed)
Messages: get-messages (bulk/search) → get-message (detailed analysis)
Streams: get-subscribed-streams → get-stream-id → get-topics-in-stream

Error Handling

All tools provide comprehensive error handling with helpful messages:

“User not found” → Points to search-users tool
“Stream not found” → Points to get-subscribed-streams
“Invalid email” → Explains to use actual emails, not display names
“Topic required” → Reminds about topic requirement for stream messages

For debugging issues, always start with the get-started tool to verify your connection and workspace access.

API Reference

Table of Contents

Resources

1. User Directory

2. Streams Directory

3. Message Formatting Guide

4. Common Patterns

Helper Tools

1. search-users

2. get-started

Message Operations

1. send-message

2. get-messages

3. get-message

4. edit-message

5. delete-message

6. add-emoji-reaction

7. remove-emoji-reaction

8. upload-file

9. get-message-read-receipts

10. create-scheduled-message

User Operations

1. get-users

2. get-user-by-email

3. get-user

4. update-status

5. get-user-groups

Stream Management

1. get-subscribed-streams

2. get-stream-id

3. get-stream-by-id

4. get-topics-in-stream

Drafts & Files

1. create-draft

2. get-drafts

3. edit-draft

4. edit-scheduled-message

Tool Selection Guide

When to use each user tool:

When to use each message tool:

Recommended Workflows:

Error Handling