zulip-mcp

Minimal, secure, read-only MCP server for reading Zulip chats from Claude Code (or any MCP client). Browse streams, topics, messages, and users — nothing can be created, modified, or deleted.

Why this exists

A security review of an existing Zulip MCP server surfaced serious issues (eval()-based remote code execution, arbitrary local file read/write, SSRF). This is a clean, minimal alternative built around a strict read-only, no-code-execution design. See Security.

Requirements

• Python 3.10+

• A Zulip account and an API key (see below)

• uv (recommended) or pip

Install

Clone the repo:

git clone https://github.com/shreyan-gupta/zulip-mcp.git
cd zulip-mcp

Then install with either uv or pip:

# Option A — uv (recommended; also installs the right Python)
uv sync

# Option B — pip + venv
python3 -m venv .venv
.venv/bin/pip install -e .

Get your Zulip API key

1. Open your Zulip instance (e.g. https://your-org.zulipchat.com).

2. Avatar → Personal settings → Account & privacy.

3. Under API key, click Manage your API key and copy it.

Add to Claude Code

Run this from inside the cloned repo ($(pwd) expands to its absolute path):

# Option A — uv
claude mcp add zulip \
  -e ZULIP_EMAIL=you@example.com \
  -e ZULIP_API_KEY=your-api-key \
  -e ZULIP_SITE=https://your-org.zulipchat.com \
  -- uv run --directory "$(pwd)" zulip-mcp

# Option B — venv entry point
claude mcp add zulip \
  -e ZULIP_EMAIL=you@example.com \
  -e ZULIP_API_KEY=your-api-key \
  -e ZULIP_SITE=https://your-org.zulipchat.com \
  -- "$(pwd)/.venv/bin/zulip-mcp"

Restart Claude Code, then try:

> List the streams I'm subscribed to
> Show messages in #engineering about "sync redesign"
> Summarize my last week of messages in #general

Tip: ask it to call get_own_profile first to confirm the connection works.

Tools

get_messages supports anchor-based pagination and combines filters (stream, topic, sender, full-text search) into a single query.

Security

This server is designed to be safe by construction:

• Read-only — cannot create, modify, or delete any Zulip data.

• No code execution — no eval(), exec(), subprocess, or dynamic imports.

• No filesystem access — tools never read or write local files.

• No telemetry — every network request goes exclusively to your Zulip instance.

• Stdio only — no HTTP listener, no open ports.

• Credentials stay local — read from env vars, never logged or returned in output.

Configuration

Configuration is via environment variables only (no .env auto-loading):

Development

uv sync --extra dev        # or: pip install -e ".[dev]"
ruff check .
pytest

The test suite is offline — it never contacts a real Zulip server.

License

MIT