Navigation: Home

Troubleshooting Guide

Solutions for common issues when using the Zulip MCP Server.

Quick Diagnosis

Start here for immediate help:

1. Test Connection

Run the get-started tool in your LLM client:

You: "Can you test the Zulip connection?"

Expected response should include:

✅ Connected to Zulip
Your email and Zulip URL
Available streams count
Quick tips

2. Check Server Status

# Test the server directly
node dist/server.js

# With debug output
DEBUG=true node dist/server.js

3. Verify Environment

# Check environment variables
echo $ZULIP_URL
echo $ZULIP_EMAIL
echo $ZULIP_API_KEY

Installation Issues

“Module not found” or “Cannot find package”

Symptoms:

Error: Cannot find module '@modelcontextprotocol/sdk'
Server fails to start

Solutions:

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Update to latest versions
npm update

# Check Node.js version (needs 18+)
node --version

“TypeScript compilation errors”

Symptoms:

Build fails with type errors
npm run build shows compilation errors

Solutions:

# Update TypeScript
npm install -g typescript@latest
npm install --save-dev typescript@latest

# Clean and rebuild
npm run clean
npm run build

# Check TypeScript version
tsc --version

“Permission denied” during installation

Symptoms:

Cannot create files or directories
npm install fails with permission errors

Solutions:

# Fix npm permissions (macOS/Linux)
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Use npx instead of global install
npx @modelcontextprotocol/inspector

# Alternative: Use Node Version Manager
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node

Connection Issues

“Missing required environment variables”

Symptoms:

Error: Missing required environment variables. Please set:
- ZULIP_URL: Your Zulip server URL
- ZULIP_EMAIL: Your bot/user email address  
- ZULIP_API_KEY: Your API key from Zulip settings

Solutions:

Create .env file:

# Create .env in project root
cat > .env << EOF
ZULIP_URL=https://your-org.zulipchat.com
ZULIP_EMAIL=your-bot@your-org.zulipchat.com
ZULIP_API_KEY=your-api-key-here
EOF

Set environment variables:

export ZULIP_URL="https://your-org.zulipchat.com"
export ZULIP_EMAIL="your-bot@your-org.zulipchat.com"
export ZULIP_API_KEY="your-api-key-here"

Verify variables are set:
```
env | grep ZULIP
```

“Connection test failed” or “Unauthorized”

Symptoms:

get-started tool returns connection errors
401 Unauthorized responses
Network timeout errors

Solutions:

Verify Zulip URL format:

# Correct format (note https://)
ZULIP_URL=https://your-organization.zulipchat.com
   
# Common mistakes to avoid:
# ❌ http://your-org.zulipchat.com (missing https)
# ❌ your-org.zulipchat.com (missing protocol)
# ❌ https://your-org.zulipchat.com/ (trailing slash)

Test credentials manually:

# Test API access with curl
curl -X GET https://your-org.zulipchat.com/api/v1/users/me \
  -u "your-bot@your-org.zulipchat.com:your-api-key"

Check bot permissions:
- Go to Zulip organization settings → Bots
- Verify bot is active and has necessary permissions
- Ensure bot can send messages to required streams
Regenerate API key:
- Go to Zulip settings → Account & privacy → API key
- Generate new API key
- Update your configuration

“Stream not found” or “User not found”

Symptoms:

Error: Stream 'general' does not exist
Error: Invalid user email

Solutions:

Use exact stream names:

You: "What streams am I subscribed to?"
[Use get-subscribed-streams tool to see exact names]

Search for users first:

You: "Search for users with 'john' in their name"
[Use search-users tool to find correct email addresses]

Check spelling and case:
- Stream names are case-sensitive
- Use exact names returned by list tools
- Avoid typos in email addresses

Configuration Issues

LLM Client Not Detecting Server

Symptoms:

No Zulip tools appear in LLM client
Client shows 0 tools available
MCP server not listed

Solutions:

Verify file paths:

# Get absolute path
pwd
# Should be something like: /Users/username/zulip-mcp-server
   
# Verify dist/server.js exists
ls -la dist/server.js

Update configuration with absolute paths:

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/absolute/path/to/zulip-mcp-server/dist/server.js"]
    }
  }
}

Restart LLM client completely after configuration changes
Check client-specific config locations:
- Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
- Cursor: .cursor-mcp/config.json in workspace
- Raycast: MCP extension settings

“Server failed to start” in LLM Client

Symptoms:

Client shows server error
Tools briefly appear then disappear
Connection timeout

Solutions:

Test server manually:

# Run server directly to see errors
node dist/server.js

Check for port conflicts:

# Kill any existing node processes
pkill -f "node.*server.js"
   
# Check for port usage
lsof -i :3000  # Adjust port if configured differently

Use debug mode:

{
  "env": {
    "ZULIP_URL": "...",
    "ZULIP_EMAIL": "...", 
    "ZULIP_API_KEY": "...",
    "DEBUG": "true"
  }
}

Runtime Issues

Tools Timing Out or Slow Responses

Symptoms:

Tools take >30 seconds to respond
Timeout errors from LLM client
Partial responses

Solutions:

Check network connectivity:

# Test Zulip API response time
time curl -X GET https://your-org.zulipchat.com/api/v1/users/me \
  -u "your-bot@your-org.zulipchat.com:your-api-key"

Reduce request size:

# Instead of getting all messages
You: "Get recent messages with limit 10"
   
# Instead of all users
You: "Search for specific users only"

Check Zulip server status:
- Verify your Zulip instance is responsive
- Check if there are any ongoing maintenance windows
- Contact Zulip administrator if issues persist

“Rate limit exceeded” Errors

Symptoms:

Error: Rate limit exceeded
429 HTTP responses
Temporary tool failures

Solutions:

Reduce request frequency:
- Batch multiple operations together
- Add delays between rapid requests
- Use more specific queries

Check rate limits:

You: "What's my current rate limit status?"
[Some tools may include rate limit info in responses]

Contact Zulip administrator:
- Request higher rate limits for your bot
- Verify bot permissions and quotas

Messages Not Sending or Formatting Issues

Symptoms:

Messages appear sent but don’t show in Zulip
Formatting not applied correctly
Special characters causing errors

Solutions:

Verify message content:

# Test with simple message first
You: "Send a simple test message to #general saying 'Hello'"
   
# Then try formatted content
You: "Send a message with **bold** and *italic* formatting"

Check topic requirements:

# For stream messages, topic is required
You: "Send to #general with topic 'Test' saying hello"

Escape special characters:
- Use \ to escape markdown characters
- Be careful with @ mentions and # stream references
- Test complex formatting in small chunks

Performance Optimization

Slow Tool Responses

Optimizations:

Use specific queries:

# Instead of: "Get all messages"
You: "Get last 10 messages from #development"
   
# Instead of: "Find all users"  
You: "Search for users named 'john'"

Batch operations:

You: "Send the same announcement to #sales, #marketing, and #support streams"

Use appropriate tools:
- search-users for discovery
- get-user-by-email for specific lookups
- get-messages for browsing
- get-message for single message details

Memory Usage

For large workspaces:

Limit concurrent requests
Use pagination when available
Restart server periodically in long-running environments

Debug Mode

Enable Detailed Logging

Environment variable:
```
DEBUG=true node dist/server.js
```

In LLM client config:

{
  "env": {
    "DEBUG": "true",
    "NODE_ENV": "development"
  }
}

Check logs:
- Look for detailed request/response information
- Identify specific API calls failing
- Check timing information

Common Debug Patterns

# Test specific API endpoints
curl -v -X GET https://your-org.zulipchat.com/api/v1/streams \
  -u "your-bot@your-org.zulipchat.com:your-api-key"

# Check server accessibility
telnet your-org.zulipchat.com 443

# Verify DNS resolution
nslookup your-org.zulipchat.com

Getting Help

Before Asking for Help

Try the get-started tool to verify basic functionality
Check recent error messages in your LLM client
Test with simple operations before complex workflows
Review configuration for typos or incorrect paths

When Reporting Issues

Include this information:

Version: Zulip MCP Server version and Node.js version
Environment: OS, LLM client, configuration method
Error messages: Complete error text or screenshots
Steps to reproduce: Minimal example that triggers the issue
Expected vs actual behavior: What you expected to happen

Resources

GitHub Issues: github.com/avisekrath/zulip-mcp-server/issues
Zulip API Docs: zulip.com/api
MCP Documentation: modelcontextprotocol.io
Node.js Troubleshooting: nodejs.org/en/docs/guides/

Emergency Recovery

Complete Reset

If nothing else works:

# 1. Stop all processes
pkill -f "node.*server"

# 2. Clean installation
rm -rf node_modules dist package-lock.json
npm install
npm run build

# 3. Reset configuration
rm .env
# Recreate .env with fresh credentials

# 4. Test directly
node dist/server.js

# 5. Restart LLM client
# Close and reopen your LLM client application

Backup Configuration

Keep working configurations backed up:

# Backup working .env
cp .env .env.backup

# Backup working LLM client config
cp ~/.config/claude/claude_desktop_config.json claude_config.backup

This allows quick recovery when experimenting with new settings.