N8n Instagram MCP

集成n8n的Instagram MCP服务器

该项目提供了一个Instagram Direct Message MCP（模型上下文协议）服务器，可以与人工智能助手（如Claude Desktop）一起使用，也可以通过HTTP API与n8n工作流集成。

目录

• 先决条件
• 安装
• 配置
• 运行服务
• 与n8n一起使用
• 与AI助手一起使用（MCP模式）
• API 文档
• 故障排除

先决条件

所需软件

1. 码头工人 （版本20.10或更高版本）

- 下载地址：https://www.docker.com/products/docker-desktop - 验证安装： docker --version

1. Docker Compose （2.0或更高版本）

- 通常包含在Docker桌面中 - 验证安装： docker compose version

1. Git （可选，用于克隆存储库）

- 下载地址：https://git-scm.com/downloads

系统要求

• macOS、Linux或Windows （适用于Windows的WSL2）
• 至少2GB的可用磁盘空间
• 至少4GB的RAM （建议8GB）
• Internet连接 用于下载Docker镜像和依赖项

安装

步骤1：设置环境变量

开始之前，您必须配置您的Instagram凭据：

1. 复制示例环境文件：

   cp .env.example .env

1. 编辑 .env 并添加您的Instagram凭据：

   nano .env
   # or use your preferred editor

1. 更新中的值 .env:

   INSTAGRAM_USERNAME=your_instagram_username
   INSTAGRAM_PASSWORD=your_instagram_password
   MODE=http

⚠️ 重要提示： 这 .env 该文件包含敏感凭据，因此被排除在版本控制之外。永远不要承诺！

步骤2：克隆或下载存储库

如果您有存储库：

cd /path/to/sussy_shit

或者，如果你需要从头开始设置它，请确保你有以下结构：

sussy_shit/
├── .env                    # Your credentials (create from .env.example)
├── .env.example            # Template file
├── docker-compose.yml
├── instagram_dm_mcp/
│   ├── Dockerfile
│   ├── docker-entrypoint.sh
│   ├── requirements.txt
│   └── src/
│       ├── mcp_server.py
│       └── http_api.py
├── mcp_data/
└── n8n_data/

步骤3：验证Docker是否正在运行

docker ps

如果您遇到错误，请启动Docker Desktop并等待其完全启动。

步骤4：创建所需目录

目录将自动创建，但您可以手动创建：

mkdir -p mcp_data/sessions mcp_data/downloads n8n_data

配置

配置是通过以下方式处理的 .env 文件（在安装步骤1中设置）。

重要安全注意事项：

• ✅ 这 .env 文件已在 .gitignore -它不会被提交到版本控制中
• ✅ 切勿将凭据提交到版本控制
• ✅ 保持你的 .env 文件安全，不共享
• ✅ 使用 .env.example 作为他人的模板

选择您的模式

Instagram MCP服务器可以在两种模式下运行：

1. HTTP模式 （适用于n8n）：设置 MODE=http

- 公开REST API终结点 - 可通过HTTP请求访问 - 最适合自动化工作流程

1. MCP模式 （适用于AI助手）：设置 MODE=mcp 或省略变量

- 使用stdio传输 - 适用于克劳德桌面、光标等。 - 无法通过HTTP访问

对于n8n集成，请使用 MODE=http.

运行服务

启动所有服务

docker compose up -d

这将：

• 构建Instagram MCP服务器映像（仅限首次）
• 拉取n8n图像（仅限第一次）
• 在后台启动两个容器

检查服务状态

docker compose ps

您应该看到这两个服务都在运行：

NAME            STATUS
instagram_mcp   Up
n8n             Up

查看日志

查看所有日志：

docker compose logs -f

仅查看Instagram MCP日志：

docker compose logs -f instagram_mcp

仅查看n8n日志：

docker compose logs -f n8n

停止服务

docker compose down

重新启动服务

docker compose restart

代码更改后重建

如果您修改了Instagram MCP代码：

docker compose build instagram_mcp
docker compose up -d instagram_mcp

与n8n一起使用

第一步：访问n8n

1. 打开浏览器并导航到： http://localhost:5678
2. 如果这是您第一次，系统将提示您创建帐户
3. 完成安装向导

步骤2：创建工作流

1. 点击 “添加工作流” 或 “新工作流”
2. 添加一个 HTTP 请求 节点

步骤3：配置HTTP请求节点

重要提示： 从n8n（在Docker中运行）调用时，使用Docker服务名称，而不是 localhost.

基本URL: http://instagram_mcp:5000

示例1：发送消息

1. 方法： POST
2. 网址： http://instagram_mcp:5000/send-message
3. 正文内容类型： JSON
4. 主体：

   {
     "username": "target_username",
     "message": "Hello from n8n!"
   }

示例2：列出聊天记录

1. 方法： POST
2. 网址： http://instagram_mcp:5000/list-chats
3. 主体：

   {
     "amount": 20,
     "selected_filter": "unread"
   }

示例3：获取用户信息

1. 方法： GET
2. 网址： http://instagram_mcp:5000/user-info/target_username

（替换 target_username 使用实际用户名）

步骤4：测试您的工作流程

1. 点击 “执行工作流” 或 “测试工作流程”
2. 检查响应-它应该包含 "success": true 如果成功

常见的n8n工作流模式

自动回复新消息

1. 计划触发器 -每5分钟跑一次
2. HTTP 请求 - POST /list-chats 随着 {"selected_filter": "unread"}
3. 代码节点 -处理未读聊天
4. HTTP 请求 - POST /list-messages 对于每个线程
5. HTTP 请求 - POST /send-message 回应

监控用户活动

1. 计划触发器 -每小时跑步一次
2. HTTP 请求 - POST /online-status 带有用户名列表
3. IF节点 -检查用户是否在线
4. HTTP 请求 - POST /send-message 通知

与AI助手一起使用（MCP模式）

如果你想用Claude Desktop或Cursor而不是n8n来使用它：

1. 集 MODE=mcp 在 docker-compose.yml （或删除MODE变量）
2. 重新启动容器： docker compose restart instagram_mcp
3. 配置MCP客户端以连接到容器

看 instagram_dm_mcp/DOCKER_HOSTING.md 了解详细的MCP客户端配置。

API 文档

交互式API文档

运行HTTP API后，请访问：

• Swagger用户界面： http://localhost:5001/docs
• 重新记录： http://localhost:5001/redoc

可用端点

消息传递

• POST /send-message -发送短信
• POST /send-photo -发送照片
• POST /send-video -发送视频
• POST /list-messages -在线程中列出消息
• POST /mark-seen -将消息标记为可见
• POST /delete-message -删除消息

聊天/话题

• POST /list-chats -列出所有聊天记录
• POST /pending-chats -列出待处理的聊天记录
• POST /search-threads -搜索线程
• POST /thread-details -获取线程详细信息
• POST /thread-by-participants -按用户ID获取线程
• POST /mute-conversation -将对话静音/取消静音

用户

• GET /user-info/{username} -获取用户信息
• GET /user-id/{username} -从用户名获取用户ID
• GET /username/{user_id} -从用户ID获取用户名
• POST /search-users -搜索用户
• POST /online-status -检查用户在线状态
• POST /user-followers -获取用户关注者
• POST /user-following -让用户被关注
• POST /user-posts -获取用户帖子
• POST /user-stories -获取用户故事

媒体

• POST /like-media -喜欢或不喜欢某个帖子
• POST /list-media-messages -在线程中列出媒体消息
• POST /download-media -从邮件下载媒体
• POST /download-shared-post -下载共享帖子/卷轴

响应格式

所有端点都返回JSON：

成功：

{
  "success": true,
  "message": "Operation completed",
  ...
}

错误：

{
  "success": false,
  "message": "Error description"
}

故障排除

容器无法启动

检查Docker是否正在运行：

docker ps

检查日志：

docker compose logs instagram_mcp

常见问题：

• 端口5001已在使用中：在中更改端口映射 docker-compose.yml
• 端口5678已在使用中：更改n8n端口映射
• 磁盘空间不足： docker system prune -a

n8n中的连接错误

“无法建立连接”错误：

1. 验证URL是否正确：

- ✅ 用途： http://instagram_mcp:5000 - ❌ 请勿使用： http://localhost:5001 （来自n8n容器）

1. 检查容器是否在同一网络上：

   docker network inspect sussy_shit_mcp-network

两者 n8n 和 instagram_mcp 应该列出来。

1. 测试n8n容器的连接：

   docker compose exec n8n wget -O- http://instagram_mcp:5000/

Instagram登录失败

检查凭据：

docker compose logs instagram_mcp | grep -i "login\|error"

常见问题：

• 用户名/密码错误
• Instagram需要2FA验证
• 帐户暂时锁定
• 速率限制

解决方案： 请稍等几分钟，然后重试，或检查您的Instagram帐户状态。

API返回错误

检查API是否正在运行：

curl http://localhost:5001/

检查日志：

docker compose logs instagram_mcp --tail 50

验证MODE是否设置为http:

docker compose exec instagram_mcp env | grep MODE

应显示： MODE=http

端口已在使用中

更改docker-compose.yml中的端口：

ports:
  - "5002:5000"  # Change 5001 to 5002

然后更新n8n个URL以使用新端口。

重建一切

如果你有持续的问题：

# Stop everything
docker compose down

# Remove volumes (WARNING: This deletes data)
docker compose down -v

# Rebuild
docker compose build --no-cache

# Start fresh
docker compose up -d

项目结构

sussy_shit/
├── README.md                    # This file
├── docker-compose.yml           # Docker Compose configuration
├── instagram_dm_mcp/            # Instagram MCP server
│   ├── Dockerfile              # Docker image definition
│   ├── docker-entrypoint.sh    # Container startup script
│   ├── requirements.txt        # Python dependencies
│   ├── src/
│   │   ├── mcp_server.py       # MCP server (stdio mode)
│   │   └── http_api.py         # HTTP API (for n8n)
│   ├── N8N_INTEGRATION.md      # Detailed n8n guide
│   └── N8N_QUICK_START.md      # Quick n8n reference
├── mcp_data/                    # Persistent data (sessions, downloads)
│   ├── sessions/               # Instagram session files
│   └── downloads/              # Downloaded media
└── n8n_data/                    # n8n data directory

其他资源

• n8n文件： https://docs.n8n.io
• Instagram MCP服务器： 看 instagram_dm_mcp/readme.md
• Docker文档： https://docs.docker.com

支持

针对以下特定问题：

• Instagram MCP服务器： 检查 instagram_dm_mcp/ 文档目录
• n8n集成： 看 instagram_dm_mcp/N8N_INTEGRATION.md
• Docker问题： 检查Docker日志和文档

许可证

请参阅各自目录中的各个组件许可证。