Mcp Instagram Agent

What is Mcp Instagram Agent

mcp_instagram_agent is an automation agent powered by MCP that utilizes Playwright to automate various interactions on Instagram, including story views, likes, comments, and follows through LLM tool calls.

Use cases

Use cases for mcp_instagram_agent include automating the process of engaging with followers, managing content interactions for brands, and conducting market research by analyzing user engagement through automated actions.

How to use

To use mcp_instagram_agent, run the server by executing ‘python server.py’. This will start the automation process, allowing you to access Instagram and perform actions like liking posts and viewing stories.

Key features

Key features of mcp_instagram_agent include the ability to automate story views, like and comment on posts, scroll through feeds, load cookies for session management, take screenshots of actions, and handle UI failures with logging.

Where to use

mcp_instagram_agent can be used in social media management, marketing automation, and user engagement strategies where automated interactions on Instagram are beneficial.

📡 server.py – Instagram Automation MCP Server

🔧 What it does

Runs a Playwright-based FastMCP server to control Instagram through a visible browser:

• Opens stories and simulates viewing
• Likes and comments on posts
• Scrolls feed
• Loads cookies from cookies/instagram.json
• Takes screenshots for every action
• Handles UI failures gracefully with logging and fallbacks

🛠️ How to run

python server.py

💻 Available Tools

• access_instagram(): Open homepage (refreshes if needed)
• like_instagram_post(post_url)
• comment_on_instagram_post(post_url, comment)
• scroll_instagram_feed(scrolls=1)
• view_instagram_stories(): Opens and simulates story view
• interact_with_story(action): One of "next", "previous", "like", "reply"
• close_instagram()

📁 Logs & Screenshots

• Logs: instagram_server.log
• Screenshots: instagram_screenshots/

🧠 client.py – Gemini + MCP Client

🔧 What it does

Connects to your MCP server via stdio, then uses Gemini to:

• Decide which tool to use based on a plain-text user query
• Call the tool and display the result

🛠️ How to run

python client.py path/to/server.py

🔁 Usage Flow

• You type: like this post https://www.instagram.com/p/xxxxx/
• Gemini picks the best tool and fills in arguments
• The client parses Gemini’s response and executes it via MCP
• You get the tool result or a Gemini parse error

✅ Dependencies

• Requires .env with:

  GEMINI_API_KEY=your-key-here
  

🔧 Pending Fixes

• [ ] Story interaction buttons sometimes invisible or hidden (tabindex=-1) — fallback via keyboard.press("ArrowRight") works but needs more robustness.
• [ ] Story viewer detection (div[role="dialog"]) is unreliable post-first interaction.
• [ ] Like/comment on feed posts hasn’t been validated end-to-end recently.
• [ ] Pause button in stories often times out — fallback logic works but may miss timing.

🚀 Future Steps

• [ ] Add detection of whether the story viewer is still open using multiple fallback methods (DOM + pixel check).
• [ ] Add auto-follow, unfollow, view profile, and save post interactions.
• [ ] Add a session tracker (e.g. track what posts were already interacted with).
• [ ] Add Instagram DM tool (optional).
• [ ] Add real-time debugging commands via a dev tool.
• [ ] Introduce screenshot diffing or pixel analysis to detect visual success (e.g. next story loaded).
• [ ] Enable headless mode with optional video recording for CI/debug.