MCP Mail (Forked from mcp_agent_mail)
A mail-like coordination layer for coding agents
> "It's like gmail for your coding agents!"
📦 Installation
Quick Install from PyPI (Recommended):```bash
pip install mcp-mail
or with uv:```bash
uv pip install mcp_mail
One-Line Installer (sets up everything):```bash
curl -fsSL https://raw.githubusercontent.com/jleechanorg/mcp_mail/main/scripts/install.sh | bash -s -- --yes
This installer:
- Installs uv if missing and updates your PATH
- Creates a Python 3.11 virtual environment
- Installs dependencies
- Starts the MCP HTTP server on port 8765
- Creates helper scripts (including `run_server_with_token.sh`)
After installation, the server listens on http://127.0.0.1:8765/mail.
**Manual Installation:**```bash
# Install uv (if you don't have it already)
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
# Clone the repo
git clone https://github.com/jleechanorg/mcp_mail
cd mcp_mail
# Create a Python 3.11 virtual environment and install
uv python install 3.11
uv venv -p 3.11
source .venv/bin/activate
uv sync
# Start the MCP server
scripts/run_server_with_token.sh
Alternative Install Sources:
🔗 Repository Links
This Fork: jleechanorg/mcp_mail •
Original: Dicklesworthstone/mcp_agent_mail
⚠️ Python Compatibility
Supported Python Versions: 3.11, 3.12, 3.13
Not Supported: Python 3.14+
MCP Mail requires Python 3.11-3.13 due to an upstream dependency incompatibility with Python 3.14. The beartype library (a transitive dependency) uses collections.abc.ByteString, which was removed in Python 3.14.
What happens if I try to use Python 3.14?
- The launcher scripts will automatically skip Python 3.14 and select 3.13, 3.12, or 3.11
- If only Python 3.14 is available, you'll see a clear error message with instructions
- The server includes a startup guard that detects Python 3.14 and exits gracefully
When will Python 3.14 be supported?
We're monitoring upstream dependencies (beartype and related packages) for Python 3.14 compatibility. Once the dependency chain is updated, we'll re-enable Python 3.14 support.
🌟 Fork Attribution
**This repository is forked from https://github.com/Dicklesworthstone/mcp_agent_mail. Full credit goes to the original author for creating this innovative multi-agent coordination system.
Full credit goes to the original author for creating this innovative multi-agent coordination system.
> Note: This was copied as a standalone repository rather than kept as a fork because Codex web appears to ignore forks in its repository indexing. Here was my first attempt at a normal fork: jleechanorg/mcp_agent_mail
Fork Improvements
This fork extends the original MCP Agent Mail with 11 core enhancements focused on removing coordination barriers and improving efficiency:
🚀 Token Efficiency
- 🎯 Lazy Loading System (Phase 2 Complete) - Reduces token usage by ~65%:
- Core mode (default): 8 essential tools + 2 meta-tools = 10 tools loaded
- Extended mode: 15 additional tools loaded on-demand via
call_extended_tool - Meta-tools:
list_extended_tools(discovery) andcall_extended_tool(invocation) - Organized into 6 functional clusters (infrastructure, identity, messaging, search, file reservations, macros)
- Configure via
MCP_TOOLS_MODEenvironment variable (core|extended) - Implementation:
src/mcp_agent_mail/app.py:2426-2476(CORE_TOOLS, EXTENDED_TOOLS, EXTENDED_TOOL_METADATA)
🌐 Global Architecture (No Boundaries)
> Projects are informational labels (e.g., repo paths, team names). They do NOT isolate agents — any agent can message any other agent regardless of project. project_key is retained for compatibility and labeling, but agent lookup and backend message queries do not use it to restrict reachability.
- 🌍 Projects as Informational Metadata - Projects don't create barriers:
- Projects are metadata only (badges, tags, context) - NOT organizational boundaries
- Unified inbox shows ALL messages regardless of project
- Backend queries ignore project filters (messages fetched by agent, not project)
- Agent lookup is global by name;
project_keyis never used to restrict which agents are reachable - Consistent treatment across all layers (UI, database, tools)
- Note:
project_keyis still used for labeling and compatibility (e.g., where artifacts are written, how projects are labeled in logs/UI) - Why: Agents work seamlessly across multiple repos/projects
- Implementation:
src/mcp_agent_mail/app.py(_get_agent,_get_message_by_id_global)
Cross-project messaging example:```python
Alice is in project "repo-frontend", Bob is in project "repo-backend"
They can still message each other directly — project is just a label
await client.call_tool("register_agent", {
"project_key": "repo-frontend", "program": "claude-code", "model": "opus-4", "name": "Alice"
})
await client.call_tool("register_agent", {
"project_key": "repo-backend", "program": "claude-code", "model": "opus-4", "name": "Bob"
})
Alice (project: repo-frontend) sends to Bob (project: repo-backend) — works seamlessly
await client.call_tool("send_message", {
"project_key": "repo-frontend",
"sender_name": "Alice",
"to": ["Bob"],
"subject": "Cross-project hello",
"body_md": "Hi from frontend!",
})
Bob fetches inbox and sees the message — even with a different project_key
inbox = await client.call_tool("fetch_inbox", {
"project_key": "repo-frontend", "agent_name": "Bob"
})
- **🎯 Globally Unique Agent Names** - Database-enforced global uniqueness:
- **Case-insensitive** uniqueness across ALL projects (prevents name collisions)
- **Auto-migration**: Existing duplicates renamed with numeric suffixes (Alice → Alice2, Alice3)
- **Flexible enforcement**: `strict` (reject duplicates), `coerce` (auto-rename), `always_auto` (generate memorable names)
- Race condition protection at database level with functional index
- Configure via `AGENT_NAME_ENFORCEMENT_MODE` environment variable
- **Implementation**: `src/mcp_agent_mail/db.py:236-302` (_migrate_agent_name_uniqueness)
- **🌍 Global Agent Lookup** - Agents accessible by name alone:
- `_get_agent_by_name()` looks up agents globally without needing project context
- Enables cross-project agent references and coordination
- Simplifies agent discovery and communication
- **Implementation**: `src/mcp_agent_mail/app.py:1569-1582`
- **🌍 Global Message Lookup** - Messages accessible across projects:
- `_get_message_by_id_global()` retrieves messages by ID regardless of project
- Agents can reply to messages they received from any project
- Eliminates "Message X not found for project Y" errors
- Tools using global lookup: `reply_message`, `mark_message_read`, `acknowledge_message`
- **Implementation**: `src/mcp_agent_mail/app.py:2312-2327`
### 🎙️ Automatic Notifications
- **📬 Global Inbox with Mention Scanning** - Never miss important messages:
- Automatic **@mention detection** when agents fetch inbox
- Scans global inbox for messages mentioning agent name (case-insensitive)
- Works in both subject and body text
- Messages marked with `"source": "global_inbox_mention"` for traceability
- Automatic deduplication (no duplicate messages)
- Falls back gracefully if global inbox unavailable
- **Implementation**: `src/mcp_agent_mail/app.py:66-68` (get_global_inbox_name), `676-711` (_ensure_global_inbox_agent)
### ⚡ Simplified Workflows
- **✅ Simplified Registration** - One-step agent onboarding:
- `register_agent` now **auto-creates projects** if they don't exist
- Eliminates need for separate `ensure_project()` call
- Automatic archive initialization and Git repo setup
- Just call `register_agent` and start sending messages
- **Implementation**: `src/mcp_agent_mail/app.py:657-673` (_ensure_project auto-called)
- **🔧 Flexible Project Keys** - Any string works as project identifier:
- **Repo names** (`myapp-frontend`, `api-backend`)
- **Custom slugs** (`team-alpha`, `prod-db`)
- **Filesystem paths** (still supported for backward compatibility)
- Not limited to absolute paths - use whatever makes sense
- Backward compatible with existing path-based keys
- **💬 Contact-Free Messaging** - No approval workflow:
- Direct agent-to-agent messaging **without approval**
- Removed contact tools: `request_contact`, `respond_contact`, `macro_contact_handshake`
- Auto-registration of missing local recipients
- Streamlines multi-agent coordination across projects
- Configure via `messaging_auto_register_recipients` (default: True)
- **⚡ Auto-Fetch Inbox** - Streamline agent registration:
- `register_agent(..., auto_fetch_inbox=True)` automatically fetches inbox after registration
- Eliminates need for separate `fetch_inbox` call
- Configurable filters: `inbox_limit`, `inbox_urgent_only`, `inbox_since_ts`
- Agents immediately see relevant messages upon joining
- **Implementation**: `src/mcp_agent_mail/app.py:3021-3159`
### 🔍 Advanced Search
- **🎯 Dual Search System** - Find messages with sophisticated ranking:
- **`search_mailbox` (CORE)**: Advanced FTS5 search with BM25 relevance scoring
- Global inbox prioritization (important messages ranked higher)
- Agent filtering and subject/body snippet highlighting
- Full message body inclusion option
- Returns detailed metadata with relevance scores
- **`search_messages` (EXTENDED)**: Simpler FTS5 search for basic queries
- Full-text search across subjects, bodies, and attachments
- Helps agents find prior work before duplicating effort
- **Implementation**:
- `search_mailbox`: `src/mcp_agent_mail/app.py:4218-4454`
- `search_messages`: `src/mcp_agent_mail/app.py:4646-4767`
Example usage:```python
# Search with relevance ranking
results = await search_mailbox(
query="authentication bug",
agent="MyAgent",
project_key="my-project",
limit=10
)
# Results sorted by relevance (BM25)
for result in results:
print(f"Score: {result['score']}, Subject: {result['subject']}")
📝 How Messages Are Stored
Every message sent through MCP Agent Mail is stored in SQLite.
SQLite Database (~/.mcp_agent_mail_git_mailbox_repo/storage.sqlite3 by default)
- Full-text search indexes (FTS5)
- Message metadata (sender, recipients, timestamps)
- Agent directory and profiles
- File reservation tracking
- Fast queries without scanning Git history
- Note: By default, the database and local artifacts live under ~/.mcp_agent_mail_git_mailbox_repo
🔄 Git Commit Flow
When an agent sends a message via send_message, here's what happens:
- Message written to
messages/YYYY/MM/.mdwith YAML frontmatter - Inbox/outbox copies created as symlinks in each agent's mailbox
- Git add all new files (canonical message + symlinks)
- Git commit with structured message:```
mail: SenderAgent -> RecipientAgent | Subject Line
TOOL: send_message
Agent: SenderAgent
Project: myproject
Started: 2025-11-11T10:30:00Z
Status: SUCCESS
Thread: thread-id-123
```
5. Commit trailers automatically appended (Agent, Thread) for traceability
Key benefits:
- Human-auditable: git log shows all agent communication
- Diffable: git diff to see message changes over time
- Blameable: git blame traces who sent what and when
- Reversible: git revert to undo problematic messages
- Portable: Clone the repo to backup or share message history
Configuration:
- Storage location: STORAGE_ROOT env var (default: ~/.mcp_agent_mail_git_mailbox_repo) for the SQLite DB and local artifacts
- Archive storage has been removed; messages are no longer written to per-project Git archives
> Important: DATABASE_URL must point to the same database for all agents.
> The default is an absolute path under your home directory:
> DATABASE_URL=sqlite+aiosqlite:///$HOME/.mcp_agent_mail_git_mailbox_repo/storage.sqlite3
> If you override it with a relative SQLite URL and run the server from different directories (e.g., multiple workspace tabs), each will create its own separate database and agents cannot see each other's messages.
> For multi-workspace or Conductor setups, set an absolute path:
>bash
> export DATABASE_URL="sqlite+aiosqlite:////home/user/.mcp_agent_mail_git_mailbox_repo/storage.sqlite3"
>
Messages are stored in SQLite by default:```bash
Just run the server - messages go to SQLite under STORAGE_ROOT by default
uv run python -m mcp_agent_mail.http
Ensure git hooks are installed (enforces Ruff/ty/Bandit on commit)
./scripts/ensure_git_hooks.sh
**🔒 Want private messages?** Use a global storage root instead:```bash
# Set STORAGE_ROOT to use a global directory outside the repo
STORAGE_ROOT=~/.mcp_agent_mail_git_mailbox_repo uv run python -m mcp_agent_mail.http
Summary: This fork removes coordination barriers by making everything global by default - agents, messages, and projects all work across boundaries. Combined with advanced search with BM25 relevance ranking, auto-fetch inbox on registration, and automatic @mention scanning, it creates a frictionless multi-agent collaboration platform with SQLite-backed storage.
A mail-like coordination layer for coding agents, exposed as an HTTP-only FastMCP server. It gives agents memorable identities, an inbox/outbox, searchable message history, and voluntary file reservation "leases" to avoid stepping on each other.
Think of it as asynchronous email + directory + change-intent signaling for your agents, backed by Git (for human-auditable artifacts) and SQLite (for indexing and queries).
Status: Under active development. The design is captured in detail in project_idea_and_guide.md (start with the original prompt at the top of that file).
Why this exists
Modern projects often run multiple coding agents at once (backend, frontend, scripts, infra). Without a shared coordination fabric, agents:
- Overwrite each other's edits or panic on unexpected diffs
- Miss critical context from parallel workstreams
- Require humans to "liaison" messages across tools and teams
This project provides a lightweight, interoperable layer so agents can:
- Register a temporary-but-persistent identity (e.g., GreenCastle)
- Send/receive GitHub-Flavored Markdown messages with images
- Search, summarize, and thread conversations
- Declare advisory file reservations (leases) on files/globs to signal intent
- Inspect a directory of active agents, programs/models, and activity
It's designed for: FastMCP clients and CLI tools (Claude Code, Codex, Gemini CLI, etc.) coordinating across one or more codebases.
From Idea Spark to Shipping Swarm
If a blank repo feels daunting, follow the field-tested workflow we documented in project_idea_and_guide.md ("Appendix: From Blank Repo to Coordinated Swarm"):
- Ideate fast: Write a scrappy email-style blurb about the problem, desired UX, and any must-have stack picks (≈15 minutes).
- Promote it to a plan: Feed that blurb to GPT-5 Pro (and optionally Grok4 Heavy / Opus 4.1) until you get a granular Markdown plan, then iterate on the plan file while it's still cheap to change. The Markdown Web Browser sample plan shows the level of detail to aim for.
- Codify the rules: Clone a tuned
AGENTS.md, add any tech-specific best-practice guides, and let Codex scaffold the repo plus Beads tasks straight from the plan. - Spin up the swarm: Launch multiple Codex panes (or any agent mix), register each identity with Agent Mail, and have them acknowledge
AGENTS.md, the plan document, and the Beads backlog before touching code. - Keep everyone fed: Reuse the canned instruction cadence from the tweet thread or, better yet, let the commercial Companion app's Message Stacks broadcast those prompts automatically so you never hand-feed panes again.
Watch the full 23-minute walkthrough (YouTube link) to see the loop in action.
Productivity Math & Automation Loop
One disciplined hour of GPT-5 Codex—when it isn't waiting on human prompts—often produces 10–20 "human hours" of work because the agents reason and type at machine speed. Agent Mail multiplies that advantage in two layers:
- Base OSS server: Git-backed mailboxes, advisory file reservations, Typer CLI helpers, and searchable archives keep independent agents aligned without babysitting. Every instruction, lease, and attachment is auditable.
- Companion stack (commercial): The iOS app + host automation can provision, pair, and steer heterogeneous fleets (Claude Code, Codex, Gemini CLI, etc.) from your phone using customizable Message Stacks, Human Overseer broadcasts, Beads awareness, and plan editing tools—no manual tmux choreography required. The automation closes the loop by scheduling prompts, honoring Limited Mode, and enforcing Double-Arm confirmations for destructive work.
Result: you invest 1–2 hours of human supervision, but dozens of agent-hours execute in parallel with clear audit trails and conflict-avoidance baked in.
TLDR Quickstart
One-line installer```bash
curl -fsSL https://raw.githubusercontent.com/jleechanorg/mcp_mail/main/scripts/install.sh | bash -s -- --yes
What this does:
- Installs uv if missing and updates your PATH for this session
- Creates a Python 3.11-3.13 virtual environment and installs dependencies with uv
- Runs the auto-detect integration to wire up supported agent tools
- Starts the MCP HTTP server on port 8765 and prints a masked bearer token
- Creates helper scripts under `scripts/` (including `run_server_with_token.sh`)
- Installs/updates, verifies, and wires the Beads `bd` CLI into your PATH via its official curl installer so the task planner is ready out of the box (pass `--skip-beads` to opt out or install manually)
- Prints a short on-exit summary of each setup step so you immediately know what changed
Prefer a specific location or options? Add flags like `--dir `, `--project-dir `, `--no-start`, `--start-only`, `--port `, or `--token `.
Already have Beads installed or want to handle it yourself? Append `--skip-beads` to the installer command to bypass the automatic `bd` setup and PATH wiring.
**Port conflicts?** Use `--port` to specify a different port (default: 8765):```bash
# Install with custom port
curl -fsSL https://raw.githubusercontent.com/jleechanorg/mcp_mail/main/scripts/install.sh | bash -s -- --port 9000 --yes
# Or use the CLI command after installation
uv run python -m mcp_agent_mail.cli config set-port 9000
If you want to do it yourself
Clone the repo, set up and install with uv in a Python 3.11-3.13 venv (install uv if you don't have it already), and then run scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh. This will automatically set things up for your various installed coding agent tools and start the MCP server on port 8765. If you want to run the MCP server again in the future, simply run scripts/run_server_with_token.sh:```bash
Install uv (if you don't have it already)
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
Clone the repo
git clone https://github.com/jleechanorg/mcp_mail
cd mcp_mail
Create a Python 3.11-3.13 virtual environment and install dependencies
Note: Python 3.14+ is NOT supported due to upstream dependency incompatibilities
uv python install 3.13
uv venv -p 3.13
source .venv/bin/activate
uv sync
Detect installed coding agents, integrate, and start the MCP server on port 8765
scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh
Later, to run the MCP server again with the same token
scripts/run_server_with_token.sh
Now, simply launch Codex-CLI or Claude Code or other agent tools in other consoles; they should have the mail tool available. See below for a ready-made chunk of text you can add to the end of your existing AGENTS.md or CLAUDE.md files to help your agents better utilize the new tools.
Change port after installation
uv run python -m mcp_agent_mail.cli config set-port 9000
## Ready-Made Blurb to Add to Your AGENTS.md or CLAUDE.md Files:```
## MCP Agent Mail: coordination for multi-agent workflows
What it is
- A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources.
- Provides identities, inbox/outbox, searchable threads, and advisory file reservations, with human-auditable artifacts in Git.
Why it's useful
- Prevents agents from stepping on each other with explicit file reservations (leases) for files/globs.
- Keeps communication out of your token budget by storing messages in a per-project archive.
- Offers quick reads (`resource://inbox/...`, `resource://thread/...`) and macros that bundle common flows.
How to use effectively
1) Same repository
- Register an identity: call `ensure_project`, then `register_agent` using this repo's absolute path as `project_key`.
- Reserve files before you edit: `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true)` to signal intent and avoid conflict.
- Communicate with threads: use `send_message(..., thread_id="FEAT-123")`; check inbox with `fetch_inbox` and acknowledge with `acknowledge_message`.
- Read fast: `resource://inbox/{Agent}?project=<abs-path>&limit=20` or `resource://thread/{id}?project=<abs-path>&include_bodies=true`.
- Tip: set `AGENT_NAME` in your environment so the pre-commit guard can block commits that conflict with others' active exclusive file reservations.
2) Across different repos in one project (e.g., Next.js frontend + FastAPI backend)
- Option A (single project bus): register both sides under the same `project_key` (shared key/path). Keep reservation patterns specific (e.g., `frontend/**` vs `backend/**`).
- Option B (separate projects): each repo has its own `project_key`; agents can message each other directly using `send_message` with cross-project addressing. Keep a shared `thread_id` (e.g., ticket key) across repos for clean summaries/audits.
Macros vs granular tools
- Prefer macros when you want speed or are on a smaller model: `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake`.
- Use granular tools when you need control: `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message`.
Common pitfalls
- "from_agent not registered": always `register_agent` in the correct `project_key` first.
- "FILE_RESERVATION_CONFLICT": adjust patterns, wait for expiry, or use a non-exclusive reservation when appropriate.
- Auth errors: if JWT+JWKS is enabled, include a bearer token with a `kid` that matches server JWKS; static bearer is used only when JWT is disabled.
Integrating with Beads (dependency-aware task planning)
Beads is a lightweight task planner (bd CLI) that complements Agent Mail by keeping status and dependencies in one place while Mail handles messaging, file reservations, and audit trails. Project: steveyegge/beads
Highlights:
- Beads owns task prioritization; Agent Mail carries the conversations and artifacts.
- Shared identifiers (e.g., bd-123) keep Beads issues, Mail threads, and commits aligned.
- Install the bd CLI via prebuilt release or Go build; see the repository for platform specifics.
Copy/paste blurb for agent-facing docs (leave as-is for reuse):```
Integrating with Beads (dependency-aware task planning)
Beads provides a lightweight, dependency-aware issue database and a CLI (bd) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging, audit trail, and file-reservation signals. Project: steveyegge/beads
Recommended conventions
- Single source of truth: Use Beads for task status/priority/dependencies; use Agent Mail for conversation, decisions, and attachments (audit).
- Shared identifiers: Use the Beads issue id (e.g., bd-123) as the Mail thread_id and prefix message subjects with [bd-123].
- Reservations: When starting a bd-### task, call file_reservation_paths(...) for the affected paths; include the issue id in the reason and release on completion.
Typical flow (agents)
1) Pick ready work (Beads)
- bd ready --json → choose one item (highest priority, no blockers)
2) Reserve edit surface (Mail)
- file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="bd-123")
3) Announce start (Mail)
- send_message(..., thread_id="bd-123", subject="[bd-123] Start: <short title>", ack_required=true)
4) Work and update
- Reply in-thread with progress and attach artifacts/images; keep the discussion in one thread per issue id
5) Complete and release
- bd close bd-123 --reason "Completed" (Beads is status authority)
- release_file_reservations(project_key, agent_name, paths=["src/**"])
- Final Mail reply: [bd-123] Completed with summary and links
Mapping cheat-sheet
- Mail thread_id ↔ bd-###
- Mail subject: [bd-###] …
- File reservation reason: bd-###
- Commit messages (optional): include bd-### for traceability
Event mirroring (optional automation)
- On bd update --status blocked, send a high-importance Mail message in thread bd-### describing the blocker.
- On Mail "ACK overdue" for a critical decision, add a Beads label (e.g., needs-ack) or bump priority to surface it in bd ready.
Pitfalls to avoid
- Don't create or manage tasks in Mail; treat Beads as the single task queue.
- Always include bd-### in message thread_id to avoid ID drift across tools.
Prefer automation? Run `uv run python -m mcp_agent_mail.cli docs insert-blurbs` to scan your code directories for `AGENTS.md`/`CLAUDE.md` files and append the latest Agent Mail + Beads snippets with per-project confirmation. The installer also offers to launch this helper right after setup so you can take care of onboarding docs immediately.
## Slack Integration
MCP Agent Mail includes full **bidirectional Slack integration**, enabling agents to communicate through Slack channels. See SLACK_BIDIRECTIONAL_SYNC.md for complete documentation.
### Automated Setup (Recommended)
Run the interactive setup script which guides you through the entire process:```bash
./scripts/setup_slack_bot.sh
This script will:
- Validate prerequisites (curl, jq)
- Generate a one-click Slack app creation URL with all scopes pre-configured
- Prompt for and securely save credentials to ~/.mcp_agent_mail_git_mailbox_repo/credentials.json
- Test your Slack connection and channel access
- Provide next steps for starting the server
Manual Setup
If you prefer manual configuration:
-
Create a Slack app at https://api.slack.com/apps
- Choose "From scratch" and name it (e.g., "MCP Agent Mail") -
Configure OAuth & Permissions (Bot Token Scopes):
-chat:write- Post messages
-chat:write.public- Post to public channels
-channels:read- List channels
-channels:history- Read message history
-groups:history- Read private channel history (optional) -
Install to workspace and copy:
- Bot User OAuth Token (starts withxoxb-)
- Signing Secret (from Basic Information page) -
Enable Event Subscriptions (for bidirectional sync):
- Set Request URL to:https://your-server.com/slack/events
- For local testing, use Cloudflare Tunnel:cloudflared tunnel --url http://localhost:8765
- Subscribe to bot events:message.channels,message.groups -
Configure credentials (choose one):
Option A: ~/.mcp_agent_mail_git_mailbox_repo/credentials.json (recommended):json
{
"SLACK_ENABLED": "true",
"SLACK_BOT_TOKEN": "xoxb-your-token-here",
"SLACK_SIGNING_SECRET": "your-signing-secret",
"SLACK_DEFAULT_CHANNEL": "C0YOUR_CHANNEL_ID",
"SLACK_SYNC_ENABLED": "true"
}
Option B: Environment variables (.env file):bash
SLACK_ENABLED=true
SLACK_BOT_TOKEN=xoxb-your-token-here
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_DEFAULT_CHANNEL=C0YOUR_CHANNEL_ID
SLACK_SYNC_ENABLED=true
- Restart the server
Features:
- Bidirectional Sync: MCP messages post to Slack, Slack replies create MCP messages
- Thread Mapping: Slack threads map to MCP
thread_idfor conversation continuity - Automatic Notifications: MCP messages automatically posted to Slack
- Manual Posting:
slack_post_message()tool for direct Slack posts - Channel Discovery:
slack_list_channels()to explore available channels - Rich Formatting: Uses Slack Block Kit for enhanced message presentation
Example:```python
Automatically notify Slack when sending an MCP message
send_message(
project_key="myproject",
agent_name="BlueWhale",
to=["GreenCastle"],
subject="Deploy completed",
body_md="Production deployment successful ✅",
importance="normal"
)
→ Slack notification appears in configured channel
Or post directly to Slack
slack_post_message(
channel="deployments",
text="🚀 Build #1234 deployed to production"
)
```
Configuration Reference
All Slack settings are configurable via ~/.mcp_agent_mail_git_mailbox_repo/credentials.json or environment variables:
| Setting | Required | Default | Description |
|---|---|---|---|
SLACK_ENABLED |
Yes | false |
Enable Slack integration |
SLACK_BOT_TOKEN |
Yes | - | Bot OAuth token (xoxb-...) |
SLACK_SIGNING_SECRET |
Recommended | - | Webhook signature verification |
…(正文过长,页面只展示前面部分,完整内容见仓库)
