使用说明

即时MCP服务器（Python）

一个轻量级、健壮的模型上下文协议（MCP）服务器，用于 即时.ai V2 API，使用FastMCP构建。

特性

38工具 涵盖6个类别（帐户、活动、潜在客户、电子邮件、分析、背景知识）
双重运输支持：HTTP（远程部署）+stdio（本地）
延迟加载：通过仅加载特定的工具类别来减少上下文窗口
多租户支持：HTTP部署的请求API密钥
全面的错误处理：详细的、可操作的错误消息
速率限制：从API响应标头自动跟踪
动态超时：搜索和批量操作的超时时间延长

快速开始

安装

# Clone or navigate to the repository
cd instantly-mcp-python

# Install with pip
pip install -e .

# Or install dependencies directly
pip install fastmcp httpx pydantic python-dotenv

配置

立即设置您的API密钥：

export INSTANTLY_API_KEY="your-api-key-here"

或者创建一个 .env 文件：

INSTANTLY_API_KEY=your-api-key-here

运行服务器

HTTP模式（建议用于远程部署）

# Using FastMCP CLI
fastmcp run src/instantly_mcp/server.py --transport http --port 8000

# Using Python directly
python -m instantly_mcp.server --transport http --port 8000

# Or with uvicorn for production
uvicorn instantly_mcp.server:mcp.app --host 0.0.0.0 --port 8000

stdio模式（本地开发）

# Using FastMCP CLI
fastmcp run src/instantly_mcp/server.py

# Using Python directly
python -m instantly_mcp.server

工具类别

账户（6个工具）

工具	说明
`list_accounts`	列出带有过滤功能的电子邮件帐户
`get_account`	获取帐户详细信息和预热状态
`create_account`	使用IMAP/SMTP凭据创建帐户
`update_account`	更新帐户设置
`manage_account_state`	暂停、恢复、预热控制、测试生命体征
`delete_account`	⚠️ 永久删除帐户

活动（8个工具）

工具	说明
`create_campaign`	创建电子邮件活动（两步过程）
`list_campaigns`	按页码列出活动
`get_campaign`	获取活动详情和序列
`update_campaign`	更新活动设置
`activate_campaign`	开始发送活动
`pause_campaign`	停止发送活动
`delete_campaign`	⚠️ 永久删除活动
`search_campaigns_by_contact`	查找联系人注册的活动

线索（12个工具）

工具	说明
`list_leads`	使用筛选功能列出潜在客户
`get_lead`	获取潜在客户详细信息
`create_lead`	创建单个潜在客户
`update_lead`	更新潜在客户(⚠️ custom_variables替换全部）
`list_lead_lists`	列出潜在客户名单
`create_lead_list`	创建潜在客户列表
`update_lead_list`	更新潜在客户列表
`get_verification_stats_for_lead_list`	获取电子邮件验证统计信息
`add_leads_to_campaign_or_list_bulk`	批量添加多达1000条潜在客户
`delete_lead`	⚠️ 永久删除潜在客户
`delete_lead_list`	⚠️ 永久删除潜在客户列表
`move_leads_to_campaign_or_list`	在活动/列表之间移动/复制潜在客户

电子邮件（6个工具）

工具	说明
`list_emails`	列出带有过滤功能的电子邮件
`get_email`	获取电子邮件详细信息
`reply_to_email`	🚨 发送真实的电子邮件回复
`count_unread_emails`	统计收件箱中未读的电子邮件
`verify_email`	验证电子邮件的可送达性
`mark_thread_as_read`	将电子邮件主题标记为已读

分析（3个工具）

工具	说明
`get_campaign_analytics`	活动指标（打开、点击、回复）
`get_daily_campaign_analytics`	日复一日的表现
`get_warmup_analytics`	账户预热指标

后台作业（2个工具）

工具	说明
`list_background_jobs`	列出带分页的异步后台作业
`get_background_job`	获取特定背景工作的详细信息

延迟加载（上下文窗口优化）

通过仅加载所需的类别来减少上下文窗口的使用：

# Load only accounts and campaigns (14 tools instead of 38)
export TOOL_CATEGORIES="accounts,campaigns"

# Load only leads and analytics
export TOOL_CATEGORIES="leads,analytics"

有效类别： accounts, campaigns, leads, emails, analytics, background_jobs

身份验证方法

服务器支持多种身份验证方法以提高灵活性：

1.基于URL的身份验证

将API密钥直接包含在URL路径中：

https://your-server.com/mcp/YOUR_API_KEY

2.报头认证

URL: https://your-server.com/mcp
Header: Authorization: YOUR_API_KEY

注意：承载令牌前缀是可选的

3.自定义标题

URL: https://your-server.com/mcp
Header: x-instantly-api-key: YOUR_API_KEY

4.环境变量

export INSTANTLY_API_KEY="your-api-key-here"

MCP客户端配置

克劳德桌面版

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

stdio模式（本地）

{
  "mcpServers": {
    "instantly": {
      "command": "python",
      "args": ["-m", "instantly_mcp.server"],
      "env": {
        "INSTANTLY_API_KEY": "your-api-key-here"
      }
    }
  }
}

带有URL认证的HTTP模式（推荐）

{
  "mcpServers": {
    "instantly": {
      "url": "https://your-server.com/mcp/YOUR_API_KEY"
    }
  }
}

带标头身份验证的HTTP模式

{
  "mcpServers": {
    "instantly": {
      "url": "https://your-server.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "your-api-key-here"
      }
    }
  }
}

光标IDE

添加到 ~/.cursor/mcp.json:

使用URL身份验证

{
  "mcpServers": {
    "instantly": {
      "url": "https://your-server.com/mcp/YOUR_API_KEY"
    }
  }
}

使用标头身份验证

{
  "mcpServers": {
    "instantly": {
      "url": "https://your-server.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "x-instantly-api-key": "your-api-key-here"
      }
    }
  }
}

DigitalOcean应用平台部署

应用程序规范

name: instantly-mcp
services:
  - name: instantly-mcp
    source:
      git:
        branch: main
        repo_clone_url: https://github.com/your-username/instantly-mcp-python.git
    build_command: pip install -e .
    run_command: python -m instantly_mcp.server --transport http --port 8080
    http_port: 8080
    instance_size_slug: basic-xxs
    instance_count: 1
    envs:
      - key: INSTANTLY_API_KEY
        scope: RUN_TIME
        type: SECRET
      - key: PORT
        scope: RUN_TIME
        value: "8080"

Dockerfile（备选）

FROM python:3.11-slim

WORKDIR /app

COPY pyproject.toml .
COPY src/ src/

RUN pip install -e .

EXPOSE 8000

CMD ["python", "-m", "instantly_mcp.server", "--transport", "http", "--host", "0.0.0.0", "--port", "8000"]

多租户HTTP模式

对于为多个用户提供服务的部署，服务器支持per-request API密钥：

# Start server without default API key
python -m instantly_mcp.server --transport http --port 8000

# Clients provide API key via header
curl -X POST http://localhost:8000/mcp \
  -H "x-instantly-api-key: user-specific-api-key" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

错误处理

服务器提供详细的、可操作的错误消息：

{
  "error": {
    "code": "invalid_api_key",
    "message": "Instantly API key is required. Provide via:\n  - INSTANTLY_API_KEY environment variable\n  - api_key parameter\n  - x-instantly-api-key header (HTTP mode)"
  }
}

速率限制

服务器自动跟踪API响应头中的速率限制：

# Access via get_server_info tool
{
  "rate_limit": {
    "remaining": 95,
    "limit": 100,
    "reset_at": "2024-01-15T12:00:00"
  }
}

项目结构

instantly-mcp-python/
├── src/
│   └── instantly_mcp/
│       ├── __init__.py          # Package exports
│       ├── server.py            # FastMCP server (~180 lines)
│       ├── client.py            # API client (~200 lines)
│       ├── models/              # Pydantic models
│       │   ├── __init__.py
│       │   ├── common.py        # Pagination
│       │   ├── accounts.py      # Account models
│       │   ├── campaigns.py     # Campaign models
│       │   ├── leads.py         # Lead models
│       │   ├── emails.py        # Email models
│       │   └── analytics.py     # Analytics models
│       └── tools/               # Tool implementations
│           ├── __init__.py      # Lazy loading logic
│           ├── accounts.py      # 6 account tools
│           ├── campaigns.py     # 8 campaign tools
│           ├── leads.py         # 12 lead tools
│           ├── emails.py        # 6 email tools
│           ├── analytics.py     # 3 analytics tools
│           └── background_jobs.py # 2 background job tools
├── pyproject.toml               # Dependencies
├── env.example                  # Environment template
└── README.md                    # This file

与TypeScript版本的比较

特性	TypeScript	Python FastMCP
代码行数	~5000+	~1500
工具注册	手动处理程序	`@mcp.tool` 装饰师
输入验证	Zod模式	Pydantic（自动）
Pydantic的错误消息	手动	自动
HTTP服务器	自定义传输	内置
上下文窗口	更大的模式	更小、更清晰

api参考

有关API的详细文档，请参阅：即时V2 API文档

许可证

MIT许可证

贡献

欢迎投稿！请打开问题或PR。