mcp_agent_mail_rust에 의해 대체됨. 이 파이썬 버전은 더 이상 유지보수되지 않습니다; 새 설치는 Rust 버전을 사용하세요.

“코딩 에이전트를 위한 지메일 같은 거예요!”

HTTP 전용 FastMCP 서버로 노출된 코딩 에이전트를 위한 메일과 유사한 조정 계층입니다. 에이전트에게 기억에 남는 신원, 받은 편지함/발신편지함, 검색 가능한 메시지 기록, 그리고 서로 상관하지 않도록 자발적인 파일 예약 "임대"를 제공합니다.

에이전트를 위한 비동기 이메일 + 디렉터리 + 변경 의도 신호라고 생각하시고, Git(사람이 감사할 수 있는 산출물)과 SQLite(인덱싱 및 쿼리)로 뒷받침됩니다.

상태: 진행 중인 개발 중입니다. 디자인은 docs/planning/project_idea_and_guide.md에 자세히 담겨 있습니다(해당 파일 상단의 원래 프롬프트부터 시작).

왜 이런 게 존재하는가

현대 프로젝트는 종종 여러 코딩 에이전트(백엔드, 프론트엔드, 스크립트, 인프라)를 동시에 실행합니다. 공유된 조정 구조가 없으면 에이전트들:

• 서로의 편집을 덮어쓰거나 예상치 못한 차이에 당황하기
• 병렬 작업 스트림에서 중요한 맥락을 놓친다
• 도구와 팀 간에 메시지를 "연결"하도록 요구하기

이 프로젝트는 에이전트들이 다음을 할 수 있도록 경량적이고 상호운용 가능한 계층을 제공합니다:

MCP Agent Mail

Superseded by mcp_agent_mail_rust. This Python version is no longer maintained; use the Rust version for new installs.

“It’s like gmail for your coding agents!”

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: Maintenance mode. This Python implementation is superseded by the Rust rewrite and is no longer actively developed; new installs should use mcp_agent_mail_rust. The original design is captured in detail in docs/planning/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, Factory Droid, 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 docs/planning/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.