MCP mail

MCP开发工具

提供方 jleechanorg

开发工具 stdio · 本地进程 OAuth 授权 社区 / 第三方 ClaudeCursorWindsurfCline
查看接入方式

MCP Mail是一个为编码代理设计的邮件式协调层,提供身份管理、收件箱/发件箱、可搜索的消息历史和文件预留功能,适用于多代理协作项目。

一句话选型结论

按资料字段整理

MCP mail 属于开发工具类 MCP 服务器,stdio · 本地进程,OAuth 授权,可直接接入 Claude、Cursor、Windsurf 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式stdio · 本地进程 鉴权OAuth 授权 部署方式本地部署
GitHub 星标 9 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

多代理协作Python本地部署邮件式协调文件预留代理通信开发工具

安装与配置

stdio · 本地进程 OAuth 授权
客户端在本机拉起子进程,数据不出本机
pip install mcp-mail

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude、Cursor、Windsurf,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude、Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
MCP mail当前 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方jleechanorg上游标注的维护方 jleechanorg
分类开发工具本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

120.1 KB
来自项目仓库与上游目录的原文,未做删改

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) and call_extended_tool (invocation)
  • Organized into 6 functional clusters (infrastructure, identity, messaging, search, file reservations, macros)
  • Configure via MCP_TOOLS_MODE environment 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_key is never used to restrict which agents are reachable
  • Consistent treatment across all layers (UI, database, tools)
  • Note: project_key is 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:

  1. Message written to messages/YYYY/MM/.md with YAML frontmatter
  2. Inbox/outbox copies created as symlinks in each agent's mailbox
  3. Git add all new files (canonical message + symlinks)
  4. 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:

  1. 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.
  2. 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:

  1. Create a Slack app at https://api.slack.com/apps
    - Choose "From scratch" and name it (e.g., "MCP Agent Mail")

  2. 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)

  3. Install to workspace and copy:
    - Bot User OAuth Token (starts with xoxb-)
    - Signing Secret (from Basic Information page)

  4. 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

  5. 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

  1. Restart the server

Features:

  • Bidirectional Sync: MCP messages post to Slack, Slack replies create MCP messages
  • Thread Mapping: Slack threads map to MCP thread_id for 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

…(正文过长,页面只展示前面部分,完整内容见仓库)

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
MCP mail 怎么安装?

在客户端按下面的安装命令接入:pip install mcp-mail。装完在客户端配置里引用同一个包或端点。

MCP mail 怎么在 Claude、Cursor、Windsurf 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

MCP mail 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

MCP mail 需要 API Key 吗?

资料标注需要OAuth 授权认证,使用前准备好对应凭据,并按最小权限配置。

MCP mail 支持哪些客户端?

资料标注支持 Claude、Cursor、Windsurf、Cline;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

MCP mail 能提供哪些能力?

资料显示能力标签包括 多代理协作、Python、Claude、开发工具。具体工具清单以官方文档为准。

MCP mail 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

MCP mail 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。