Muntuai Mcp

MuntuAI MCP

此仓库包含在线 MuntuAI MCP 服务的公开文档、清单和参考客户端。可运行的服务实现位于 Muntu 后端主项目中。

MuntuAI 的官方 Model Context Protocol（MCP）服务，旨在让 MuntuAI 上的 AI Agent 通过编程方式访问邮件触达营销活动、潜在客户管理、域名基础设施和实时工作区事件。

---

这是什么

MuntuAI 是一个原生支持 AI 的邮件触达平台。此 MCP 服务允许外部 Agent（Claude、Cursor、自定义脚本）连接到 MuntuAI 工作区并执行操作：创建营销活动、导入潜在客户、验证域名、发送邮件，以及订阅 webhook 事件——所有操作均通过基于 HTTP 的标准 MCP 接口完成。

协议： 基于 HTTP 的 Model Context Protocol（JSON-RPC 2.0）
传输方式： Streamable HTTP（text/event-stream 或 application/json）
服务协议修订版本： 2025-03-26
服务 URL： https://api.muntuai.com/api/mcp

---

快速开始

1. 获取 Agent 密钥

登录 app.muntuai.com，前往 设置 → Agent 密钥，然后创建密钥。选择符合 Agent 所需权限的自主级别：

级别	可执行的操作
observer	读取所有内容——营销活动、潜在客户、域名、发件人、事件
copilot	读取、创建和修改——营销活动、域名、发件人、潜在客户、webhook
autonomous	以上所有操作，以及暂停、恢复和删除

原始密钥只会显示一次：mnt_<keyId>.<secret>。请立即复制。

2. 配置客户端

安全提示：请将原始 Agent 密钥存储在环境变量或密钥管理器中。不要将其提交到源代码管理中，也不要粘贴到共享文件里。

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "muntu": {
      "url": "https://api.muntuai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MUNTU_AGENT_KEY}"
      }
    }
  }
}

Cursor（.cursor/mcp.json 或“设置 → MCP”）：

{
  "mcpServers": {
    "muntu": {
      "url": "https://api.muntuai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MUNTU_AGENT_KEY}"
      }
    }
  }
}

Python：

pip install requests
export MUNTU_AGENT_KEY="mnt_YOUR_KEY_HERE"
python clients/python/muntu_mcp_client.py list-campaigns

建议：

export MUNTU_SESSION_ID="$(uuidgen)"

Muntu 使用可选的 MUNTU_SESSION_ID，将请求归入同一个逻辑 MCP 会话，以便应用会话范围的安全控制和预算管理。

3. 发起首次调用

连接后，向 Agent 提问：

“列出我的 MuntuAI 工作区中的所有营销活动”

Agent 将对 muntu://campaigns/{workspaceId} 调用 resources/read，并返回营销活动列表。

或通过 Python CLI 调用：

python clients/python/muntu_mcp_client.py list-campaigns
python clients/python/muntu_mcp_client.py list-domains
python clients/python/muntu_mcp_client.py list-emails

---

Agent 可以执行的操作

资源（只读视图）

资源	URI	说明
工作区	muntu://workspace/{id}	个人资料、策略、基础设施计数
域名	muntu://domains/{id}?cursor=0&limit=50	所有域名及其 DNS 和验证状态
发件人	muntu://senders/{id}?cursor=0&limit=50	所有电子邮件账户及其状态
营销活动	muntu://campaigns/{id}?cursor=0&limit=20	统一的营销活动列表
营销活动计划	muntu://campaign-plans/{id}?cursor=0&limit=20	草稿审核队列
事件	muntu://events/{id}?cursor=0	最近的系统事件（可筛选）

工具（共 30 个）

按领域分组——完整索引请参阅 tools/README.md。

• 营销活动 — 创建、启动、暂停、恢复、监控、审核草稿、发送
• 潜在客户 — 从数组或 CSV URL 导入、补充信息、抽样
• 发件人 — 创建、删除、健康检查、分配至营销活动
• 域名 — 添加、验证、检查状态
• 电子邮件生成 — 预览、优化、生成营销活动指南
• Webhooks — 订阅工作区事件
• 元数据 — 获取 Agent 密钥信息

---

仓库结构

muntuai-mcp/
├── README.md                    # This file
├── QUICKSTART.md                # 5-minute setup guide
├── docs/
│   ├── authentication.md        # Token format, headers, rate limits
│   ├── autonomy-levels.md       # Permission model
│   ├── resources.md             # All 6 resources with schemas
│   ├── events.md                # All event types and payloads
│   ├── webhooks.md              # Register, sign, verify
│   └── errors.md                # Error codes and handling
├── tools/
│   ├── README.md                # Full tool index
│   ├── campaigns.md
│   ├── leads.md
│   ├── senders.md
│   ├── domains.md
│   ├── email-generation.md
│   └── meta.md
├── workflows/
│   ├── README.md                # What workflows are
│   ├── launch-first-campaign.md
│   ├── review-and-send-drafts.md
│   ├── domain-setup.md
│   └── monitor-campaign.md
├── reference/
│   ├── event-types.md
│   ├── resource-schemas.md
│   └── tool-schemas.md
├── clients/
│   └── python/
│       ├── muntu_mcp_client.py  # Reference Python client
│       ├── README.md
│       └── examples/
├── agent-guides/
│   ├── for-claude.md
│   ├── for-cursor.md
│   └── decision-guide.md
└── .well-known/
    └── mcp-manifest.json        # Machine-readable capabilities manifest

---

核心概念

工作区 — MuntuAI 中的所有数据都限定在工作区内。你的 Agent 密钥绑定到一个工作区，只能访问其中的数据。

自主级别 — 每个工具都有最低要求级别。如果你的密钥级别低于该要求，调用将被拒绝，并记录此次尝试。请参阅 docs/autonomy-levels.md。

营销活动生命周期 — uploaded → enriching → drafting → sending → completed。Agent 可以通过 get_campaign_performance 和事件资源查看此生命周期。请参阅 workflows/monitor-campaign.md。

域名验证 — 发送邮件前，必须先通过电子邮件服务提供商验证域名。这需要发布 DNS 记录并触发验证。请参阅 workflows/domain-setup.md。

---

支持

• 文档问题： 在此仓库中提交 issue
• 平台支持： [email protected]
• 网站： muntuai.com