简介

为电子邮件活动和潜在客户管理功能提供对Instantly API v2的访问。

简介

为电子邮件活动和潜在客户管理功能提供对Instantly API v2的访问。

Instantly MCP 服务器

为 Instantly API v2 提供的 MCP 服务器，提供电子邮件营销活动和潜在客户管理功能的访问。

关于 Instantly API

Instantly API v2 是一个 RESTful API，它提供了对 Instantly 平台的各种资源和功能的访问，包括：

• 营销活动管理
• 潜在客户管理
• 电子邮件处理和验证
• 分析
• 帐户管理
• 黑名单管理
• 等等

此 MCP 服务器实现了这些端点的一个子集，以便轻松访问最常用的功能。

API 参考

完整的 Instantly API v2 文档可在以下位置获取：

• API 探索器
• API 架构
• 分析端点

所有 API 请求的基本 URL 是：https://api.instantly.ai/api/v2

工具

此 MCP 服务器实现了映射到 Instantly API v2 端点的以下工具：

1. instantly_create_lead

   • API Endpoint: POST /api/v2/leads
   • Create a new lead
   • Inputs:
     • email (string)
     • first_name (optional string)
     • last_name (optional string)
     • company_name (optional string)
     • campaign (optional string, uuid)
     • list_id (optional string, uuid)
     • personalization (optional string)
     • website (optional string)
     • phone (optional string)
     • custom_variables (optional object)

2. instantly_get_lead

   • API Endpoint: GET /api/v2/leads/{id}
   • Get details of a lead by ID
   • Input: id (string, uuid)
   • Returns: lead details

3. instantly_list_leads

   • API Endpoint: POST /api/v2/leads/list
   • List leads with optional filters
   • Inputs:
     • campaign (optional string, uuid)
     • list_id (optional string, uuid)
     • limit (optional number)
     • starting_after (optional string)
   • Returns: array of leads

4. instantly_update_lead

   • API Endpoint: PATCH /api/v2/leads/{id}
   • Update a lead's information
   • Inputs:
     • id (string, uuid)
     • first_name (optional string)
     • last_name (optional string)
     • company_name (optional string)
     • personalization (optional string)
     • website (optional string)
     • phone (optional string)
     • custom_variables (optional object)

5. instantly_delete_lead

   • API Endpoint: DELETE /api/v2/leads/{id}
   • Delete a lead
   • Input: id (string, uuid)

6. instantly_list_campaigns

   • API Endpoint: GET /api/v2/campaigns
   • List campaigns with pagination support
   • Inputs:
     • limit (optional number, default 5, max 100)
     • starting_after (optional string) - For pagination, use the next_starting_after value from the previous response
     • status (optional number) - Filter campaigns by status (0: Draft, 1: Active, 2: Paused, 3: Completed, 4: Running Subsequences)
   • Returns: array of campaigns with pagination information
   • Pagination:
     • First request: Call without starting_after
     • Subsequent pages: Use the next_starting_after value from the previous response
     • When there are no more pages, the response will not contain a next_starting_after value
   • Example: To get only active campaigns, use status: 1

7. instantly_get_campaign

   • API Endpoint: GET /api/v2/campaigns/{id}
   • Get details of a campaign
   • Input: id (string, uuid)
   • Returns: campaign details

8. instantly_get_warmup_analytics

   • API Endpoint: POST /api/v2/accounts/warmup-analytics
   • Get warmup analytics for specified email accounts
   • Input: emails (array of strings)
   • Returns: Health scores and metrics for email warmup performance
   • Useful for monitoring email deliverability and account health

9. instantly_test_account_vitals

   • API Endpoint: POST /api/v2/accounts/test/vitals
   • Test the health and connectivity of email accounts in your Instantly workspace
   • Input: accounts (array of strings) - Can test multiple email addresses at once
   • Returns:
     • Overall test status
     • Summary of successful and failed accounts
     • Detailed information for each account including provider details
     • Troubleshooting recommendations for failed accounts
   • Helps identify issues with email account configuration, authentication, and API access
   • Example: {"accounts": ["user@example.com", "sales@company.com"]}

10. instantly_get_campaign_analytics

    • API Endpoint: GET /api/v2/campaigns/analytics
    • Get performance metrics for campaigns over a specified time period
    • Inputs:
      • id (optional string) - Campaign ID for a specific campaign
      • start_date (string) - Start date in YYYY-MM-DD format
      • end_date (string) - End date in YYYY-MM-DD format
    • Returns: Comprehensive metrics including open rates, reply rates, lead counts and opportunity data

分析端点

Instantly API 提供了强大的分析端点，用于监控您的电子邮件活动和账户的性能：

1. 获取预热分析

   • API 端点: POST /api/v2/accounts/warmup-analytics
   • 描述: 为指定的电子邮件账户检索预热分析数据
   • 所需权限范围: accounts:read, accounts:all, all:read 或 all:all
   • 请求体:

     {
       "emails": ["user@example.com"]
     }
     

   • 响应: 提供关于已发送邮件、收件箱投放、垃圾邮件投放和接收邮件的日度和汇总数据，以及每个账户的健康评分

2. 测试账户重要指标

   • API 端点: POST /api/v2/accounts/test/vitals
   • 描述: 测试电子邮件账户的健康状况和连接性
   • 所需权限范围: accounts:read, accounts:all, all:read 或 all:all
   • 请求体:

     {
       "accounts": ["user@example.com"]
     }
     

   • 响应: 返回成功和失败列表，包含有关账户状态和检测到的问题的详细信息

3. 获取活动分析

   • API 端点: GET /api/v2/campaigns/analytics
   • 描述: 检索一个或多个活动的性能指标
   • 查询参数:
     • id (可选): 特定活动的 ID
     • start_date: 分析期间的开始日期
     • end_date: 分析期间的结束日期
   • 响应: 返回全面的活动统计信息，包括：
     • 总线索数
     • 已联系的线索数
     • 邮件打开次数
     • 回复次数
     • 跳出次数
     • 取消订阅次数
     • 完成次数
     • 发送的邮件数量
     • 新联系的线索数
     • 总机会数
     • 总机会价值

有关请求参数和响应格式的详细信息，请参阅 Instantly Analytics API 文档。

其他 Instantly API 端点

Instantly API v2 包含许多未在此 MCP 服务器中实现的其他端点，包括：

• 活动管理:

  • 创建活动: POST /api/v2/campaigns
  • 激活活动: POST /api/v2/campaigns/{id}/activate
  • 暂停活动: POST /api/v2/campaigns/{id}/pause
  • 更新活动: PATCH /api/v2/campaigns/{id}

• 电子邮件:

  • 回复电子邮件: POST /api/v2/emails/reply
  • 列出电子邮件: GET /api/v2/emails
  • 获取电子邮件: GET /api/v2/emails/{id}
  • 计算未读电子邮件数量: GET /api/v2/emails/unread/count

• 账户管理:

  • 这些端点现在作为工具在此 MCP 服务器中可用！请参阅下面的“账户管理工具”部分。

• 电子邮件验证:

  • 验证电子邮件: POST /api/v2/email-verification

• 线索列表:

  • 创建列表: POST /api/v2/lead-lists
  • 列出线索列表: GET /api/v2/lead-lists

对于所有可用端点的完整参考，请参阅 Instantly API Explorer。

设置

API 密钥

从您的 Instantly 账户设置中获取一个 Instantly API 密钥：

1. 前往 Instantly 仪表板中的集成页面
2. 点击左侧边栏中的“API 密钥”部分
3. 点击“创建 API 密钥”按钮
4. 输入您的 API 密钥名称
5. 选择您希望此密钥访问的范围
6. 创建并复制您的 API 密钥（注意：它只会显示一次）

与 Claude 桌面版一起使用

将以下内容添加到您的 claude_desktop_config.json 文件中：

Docker

{
  "mcpServers": {
    "instantly": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "INSTANTLY_API_KEY",
        "mcp/instantly"
      ],
      "env": {
        "INSTANTLY_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

NPX

{
  "mcpServers": {
    "instantly": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-instantly"
      ],
      "env": {
        "INSTANTLY_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

构建

Docker 构建命令：

docker build -t mcp/instantly -f Dockerfile .

认证

Instantly API v2 使用 Bearer token 认证。您的 API 密钥应包含在所有请求的 Authorization 标头中：

Authorization: Bearer YOUR_API_KEY

当您通过环境变量提供 API 密钥时，MCP 服务器会自动处理这一点。

许可

本 MCP 服务器根据 MIT 许可证许可。这意味着您可以自由地使用、修改和分发该软件，但需遵守 MIT 许可证的条款和条件。更多详情，请参见项目仓库中的 LICENSE 文件。

账户管理工具

本 MCP 服务器实现了以下账户管理工具：

1. instantly_create_account

   • API Endpoint: POST /api/v2/accounts
   • Create a new email account in Instantly
   • Inputs:
     • email (string): Email address of the account
     • first_name (string): First name associated with the account
     • last_name (string): Last name associated with the account
     • provider_code (number): Provider code (1: Custom IMAP/SMTP, 2: Google, 3: Microsoft, 4: AWS)
     • imap_username (string): IMAP username
     • imap_password (string): IMAP password
     • imap_host (string): IMAP host (e.g. imap.gmail.com)
     • imap_port (number): IMAP port (e.g. 993)
     • smtp_username (string): SMTP username
     • smtp_password (string): SMTP password
     • smtp_host (string): SMTP host (e.g. smtp.gmail.com)
     • smtp_port (number): SMTP port (e.g. 587)
     • daily_limit (optional number): Daily email sending limit
     • tracking_domain_name (optional string): Tracking domain name

2. instantly_list_accounts

   • API Endpoint: GET /api/v2/accounts
   • List email accounts in Instantly with automatic pagination
   • Inputs:
     • limit (optional number): The number of accounts to return per page (max 100, default 10)
     • starting_after (optional string): The ID of the last item in the previous page - used for pagination
     • search (optional string): Search term to filter accounts
     • status (optional number): Status filter (1: Active, 2: Paused, -1: Connection Error, -2: Soft Bounce Error, -3: Sending Error)
     • provider_code (optional number): Provider code filter (1: Custom IMAP/SMTP, 2: Google, 3: Microsoft, 4: AWS)
     • fetch_all (optional boolean): Whether to automatically fetch all pages and provide a comprehensive summary. Use this to get information about all accounts.
   • Pagination:
     • Default behavior: Returns a single page of results with a link to the next page
     • With fetch_all=true: Automatically fetches all pages and returns a comprehensive summary of all accounts, including:
       • Total account count
       • Account distribution by provider
       • Account distribution by status
       • Sample of accounts for reference

3. instantly_get_account

   • API Endpoint: GET /api/v2/accounts/{email}
   • Get details of a specific email account in Instantly
   • Input: email (string): Email address of the account to retrieve

4. instantly_update_account

   • API Endpoint: PATCH /api/v2/accounts/{email}
   • Update an existing email account in Instantly
   • Inputs:
     • email (string): Email address of the account to update
     • first_name (optional string): First name associated with the account
     • last_name (optional string): Last name associated with the account
     • daily_limit (optional number): Daily email sending limit
     • tracking_domain_name (optional string): Tracking domain name
     • skip_cname_check (optional boolean): Whether to skip CNAME check for tracking domain
     • remove_tracking_domain (optional boolean): Whether to remove tracking domain from the account

5. instantly_delete_account

   • API Endpoint: DELETE /api/v2/accounts/{email}
   • Delete an email account from Instantly
   • Input: email (string): Email address of the account to delete

6. instantly_pause_account

   • API Endpoint: POST /api/v2/accounts/{email}/pause
   • Pause an email account in Instantly
   • Input: email (string): Email address of the account to pause

7. instantly_resume_account

   • API Endpoint: POST /api/v2/accounts/{email}/resume
   • Resume a paused email account in Instantly
   • Input: email (string): Email address of the account to resume

工具测试状态

我们已经彻底测试了此 MCP 服务器中实现的所有工具，以确保它们能与 Instantly API v2 正确配合工作。以下是测试状态的摘要：

有关测试过程和结果的更多详细信息，请参阅仓库中的 Testing.md。

已知问题

• 当前在没有特定电子邮件过滤器的情况下尝试列出潜在客户时，instantly_list_leads 工具会返回 "无效的电子邮件地址" 的 API 错误。我们已尝试多种方法来解决这个问题，包括：

  • 使用 contacts 数组参数进行电子邮件搜索
  • 实现自动重试并使用空请求体
  • 各种参数格式化方法

  我们将在未来的版本中继续努力解决这个问题。

开发环境设置

如果你想为此项目贡献代码或本地运行用于开发：

1. 克隆仓库：

   git clone https://github.com/bcharleson/Instantly-MCP.git
   cd Instantly-MCP
   

2. 安装依赖项：

   npm install
   

3. 在根目录下创建一个 .env 文件，并填入你的 Instantly API 密钥：

   INSTANTLY_API_KEY=your_api_key_here
   

   ⚠️ 重要：切勿将你的 .env 文件或 API 密钥提交到版本控制。.env 文件已被包含在 .gitignore 中，以防意外提交。

4. 构建项目：

   npm run build
   

5. 运行服务器：

   node dist/index.js
   

贡献指南

欢迎贡献！如果你想要贡献：

1. 分叉仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 进行修改
4. 提交更改 (git commit -m 'Add some amazing feature')
5. 推送到分支 (git push origin feature/amazing-feature)
6. 打开 Pull Request

在提交拉取请求之前，请确保：

• 你的代码遵循项目的编码风格
• 你已为新功能添加了测试
• 所有测试均已通过
• 如有必要，你已更新了文档

服务配置

[{'mcpServers': {'instantly': {'args': ['-y', '@modelcontextprotocol/server-instantly'], 'command': 'npx', 'env': {'INSTANTLY_API_KEY': '<YOUR_API_KEY>'}}}}]

来源

• 来源：github
• 链接：https://github.com/bcharleson/instantly-mcp