内容
# 🤖 Instagram 控制 MCP 服务器
<div align="center">
[](https://pypi.org/project/instagram-mcp-server/)
[](https://github.com/official-Arvind/instagram-mcp/releases)
[](LICENSE)
[](https://modelcontextprotocol.io)
**一个专业的、全功能的模型上下文协议（MCP）服务器，使 AI 代理（如 Claude Desktop、Cursor 和自定义包装器）能够完全控制和管理 Instagram 账户，就像人类用户一样。**
[关键功能](#-关键功能) • [安装](#-安装) • [客户端配置](#%EF%B8%8F-客户端配置) • [身份验证](#-身份验证流程) • [工具参考](#-工具参考) • [安全指南](#-速率限制--安全)
</div>
---
## ⚡ 概述
**Instagram 控制 MCP 服务器** 通过封装 `instagrapi` 并利用 `FastMCP`，将大型语言模型与 Instagram 私有移动 API 连接起来。这种集成使 AI 代理具备 **68 个细粒度工具**，可以执行从媒体发布、直接消息到关系管理、故事上传和标签探索等各种操作。
与简单的图 API 包装器不同，该服务器适用于标准消费者账户，自动处理 **会话持久性**，支持 **两步验证（2FA）**，并交互式地解决 SMS/电子邮件挑战提示。
---
## 🛠️ 关键功能
* 📦 **生产就绪** — 直接通过 `pip` 安装或本地运行。
* 🔐 **无缝身份验证** — 会话 cookie、用户名/密码、2FA 和 SMS/电子邮件验证挑战处理程序。
* 🚀 **自动持久性** — 本地保存会话，以绕过重复登录并防止登录标志。
* 📸 **丰富的媒体发布** — 支持单张照片帖子、轮播相册、视频动态和短视频。
* 📖 **交互式故事** — 直接将照片/视频上传到故事中。
* 💬 **无缝直接消息** — 读取线程、标记为已读、发送文本、照片或视频消息。
* 👥 **社交和互动** — 无障碍互动：点赞、取消点赞、评论、关注、取消关注、屏蔽和列出关注者。
* 🔍 **上下文发现** — 搜索用户、标签、位置、亮点和类似配置文件。
---
## 🚀 安装
您可以将此服务器作为全局包从 **PyPI** 运行，也可以克隆它进行本地修改。
### 选项 A：从 PyPI 安装（推荐）
安装包并注册全局 CLI 入口点 `instagram-mcp`：
```bash
pip install instagram-mcp-server
```
### 选项 B：本地设置（开发）
克隆存储库，创建虚拟环境并安装依赖项：
```bash
git clone https://github.com/official-Arvind/instagram-mcp.git
cd instagram-mcp
python -m venv venv
# Windows
venv\Scripts\pip install -e .
# Mac/Linux
venv/bin/pip install -e .
```
---
## ⚙️ 客户端配置
配置您喜欢的 MCP 主机以定位可执行文件。
### 1. Claude Desktop
将以下内容添加到您的 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）或 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
```json
{
"mcpServers": {
"instagram-control": {
"command": "instagram-mcp"
}
}
}
```
*如果使用虚拟环境，请手动指定可执行文件的绝对路径：*
```json
{
"mcpServers": {
"instagram-control": {
"command": "C:\\path\\to\\instagram-mcp\\venv\\Scripts\\instagram-mcp.exe"
}
}
}
```
### 2. Cursor IDE
1. 打开 **设置** → **功能** → **MCP**。
2. 点击 **+ 添加新的 MCP 服务器**。
3. 填写参数：
* **名称**：`instagram-control`
* **类型**：`command`
* **命令**：`instagram-mcp` *(或虚拟环境可执行文件的路径)*
---
## 🔐 身份验证流程
要允许您的 AI 代理操作您的账户，请使用以下方法之一。
### 方法 1：会话 Cookie（推荐和最安全）
绕过凭证输入，避免触发 2FA 阻止，并模拟现有的浏览器会话。
1. 在桌面浏览器上登录 Instagram。
2. 打开 **开发者工具（F12）** → 进入 **应用程序（Chrome）** 或 **存储（Firefox）** → **Cookie**。
3. 选择 `https://www.instagram.com` 并复制 `sessionid` cookie 的值。
4. 指示您的代理：
> *"使用会话 ID 登录，用户名为 'your_username'，会话 ID 为 'copied_cookie_value'"*
### 方法 2：用户名和密码
如果不使用会话 cookie，请使用用户名和密码提示代理：
```
instagram_login_with_credentials(username="your_username", password="your_password")
```
* **两步验证**：如果登录请求触发 2FA，代理将收到挑战响应。提供代码：
`instagram_complete_2fa(code="123456")`
* **安全验证**：如果 Instagram 发送挑战检查（电子邮件/SMS 验证），请提供代码：
`instagram_complete_challenge(code="123456")`
### 会话生命周期
身份验证成功后，服务器会在当前目录的 `instagram_session.json` 中保存加密的会话 cookie。后续运行将自动恢复此会话，无需登录提示。
---
## 📂 工具参考
服务器公开 **68 个专门工具**。以下是功能分解：
<details>
<summary><b>🔐 身份验证和会话</b></summary>
* `instagram_login_with_sessionid` — 通过浏览器 cookie 会话绕过身份验证。
* `instagram_login_with_credentials` — 使用用户名 + 密码身份验证。
* `instagram_complete_2fa` — 提交两步验证代码。
* `instagram_complete_challenge` — 提交 SMS/电子邮件挑战验证代码。
* `instagram_get_login_status` — 查询会话生命周期状态。
* `instagram_logout` — 清除本地会话数据并断开连接。
</details>
<details>
<summary><b>📸 媒体发布和内容管理</b></summary>
* `instagram_post_photo` — 上传单张图片（支持标题、标签和位置）。
* `instagram_post_album` — 上传轮播帖子（最多 10 张图片）。
* `instagram_post_video` — 上传标准视频内容。
* `instagram_post_reel` — 发布短视频（支持自定义缩略图和封面页）。
* `instagram_delete_post` — 按媒体 PK 删除动态。
* `instagram_get_user_feed` — 检索任何配置文件的已发布帖子。
* `instagram_get_timeline_feed` — 获取首页时间线。
* `instagram_get_media_info` — 查看任何帖子的精确 JSON 元数据。
* `instagram_download_post` — 直接将媒体项目保存到磁盘。
</details>
<details>
<summary><b>📖 故事和亮点</b></summary>
* `instagram_post_photo_story` — 发布照片故事（支持链接/标签贴纸）。
* `instagram_post_video_story` — 发布视频故事（支持链接/标签贴纸）。
* `instagram_get_user_stories` — 获取任何目标账户的活跃故事。
* `instagram_delete_story` — 删除活跃故事。
* `instagram_get_story_viewers` — 获取故事浏览者的列表。
* `instagram_get_highlights` — 获取配置文件上的亮点类别。
* `instagram_create_highlight` — 将选定的活跃故事捆绑成新的亮点。
* `instagram_delete_highlight` — 删除自定义亮点。
</details>
<details>
<summary><b>💬 直接消息</b></summary>
* `instagram_get_direct_threads` — 获取正在进行的聊天线程和收件箱列表。
* `instagram_get_direct_messages` — 从线程中检索历史记录/聊天日志。
* `instagram_send_direct_message` — 发送文本直接消息。
* `instagram_send_dm_photo` — 在线程中发送照片附件。
* `instagram_send_dm_video` — 在线程中发送视频附件。
* `instagram_mark_thread_seen` — 将传入的消息标记为已读。
</details>
<details>
<summary><b>❤️ 社交互动</b></summary>
* `instagram_like_post` / `instagram_unlike_post` — 在动态上切换点赞。
* `instagram_save_post` / `instagram_unsave_post` — 切换收藏。
* `instagram_comment_on_post` — 发布新的评论。
* `instagram_reply_to_comment` — 在评论 ID 下回复线程。
* `instagram_delete_comment` — 删除评论实例。
* `instagram_like_comment` — 点赞评论目标。
* `instagram_get_post_comments` — 列出帖子下的评论。
</details>
<details>
<summary><b>👥 配置文件和关系</b></summary>
* `instagram_get_profile` — 获取任何配置文件的元数据。
* `instagram_edit_profile` — 修改姓名、简介和外部链接。
* `instagram_change_profile_picture` — 更新配置文件照片。
* `instagram_follow_user` / `instagram_unfollow_user` — 切换关注状态。
* `instagram_get_followers` / `instagram_get_following` — 查询社交图谱。
* `instagram_block_user` / `instagram_unblock_user` — 管理封锁列表。
* `instagram_get_blocked_users` — 查看当前封锁。
* `instagram_get_notifications` — 读取当前活动通知（点赞、标签、评论）。
* `instagram_get_pending_follow_requests` — 列出传入的关注请求。
</details>
---
## ⚠️ 速率限制和安全
由于此服务器使用私有客户端层连接，因此它受到 Instagram 的速率限制过滤器的影响。**为了防止账户暂停或临时封锁，请遵守以下准则：**
1. **避免高频率操作** — 分散发布、点赞和消息操作。不要编写执行多个社交操作而快速连续执行的循环脚本。
2. **模拟人类时间** — 如果编写例行程序，请在事件之间注入随机延迟（`time.sleep(20, 60)`）。
3. **预热新账户** — 新创建的配置文件会被自动化阻止。 使用已建立的账户或逐渐预热新账户。
4. **使用 Cookie 会话** — Cookie 登录触发的 security 标志远少于标准用户名/密码身份验证。
---
## 🛡️ 免责声明
该软件仅用于教育目的。它与 Instagram 的私有 API 进行交互，**不** 由 Meta Platforms Inc. 支持、关联或认可。继续自动化可能会导致临时限制、影子封禁或永久关闭您的账户。请自担风险，负责任地使用。
---
## 📄 许可证
在 **MIT License** 下分发。有关更多详细信息，请参见 [LICENSE](LICENSE)。
