@mcpware/ig-mcp - npm Package Compare versions

Comparing version 1.0.0 to 1.0.2

package.json

 {
   "name": "@mcpware/ig-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Instagram MCP server — 23 tools for the Instagram Graph API. Manage posts, comments, DMs, stories, hashtags, reels, carousels, and analytics.",
@@ -37,3 +37,3 @@ "type": "module",
     "type": "git",
-    "url": "https://github.com/ithiria894/ig-mcp-ts"
+    "url": "https://github.com/mcpware/ig-mcp"
   },
@@ -40,0 +40,0 @@ "dependencies": {

README.md

 # @mcpware/ig-mcp
 
-Instagram MCP server — 23 tools for the Instagram Graph API via [Model Context Protocol](https://modelcontextprotocol.io).
+[![npm version](https://img.shields.io/npm/v/@mcpware/ig-mcp.svg)](https://www.npmjs.com/package/@mcpware/ig-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
+[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)
 
+Instagram MCP server — **23 tools** for the Instagram Graph API via [Model Context Protocol](https://modelcontextprotocol.io).
+
 Manage posts, comments, DMs, stories, hashtags, reels, carousels, and analytics from Claude Code, Cursor, or any MCP client.
@@ -33,11 +39,89 @@
 - **Instagram Business or Creator account** (personal accounts are not supported by the Graph API)
-- **Meta long-lived access token** with permissions:
-  - `instagram_basic` — profile info, media
-  - `instagram_content_publish` — publish posts, reels, carousels
-  - `instagram_manage_comments` — read/write comments
-  - `instagram_manage_insights` — analytics
-  - `instagram_manage_messages` — DMs (requires Advanced Access from Meta)
-  - `pages_show_list` — connected Facebook pages
-- **Instagram Business Account ID** — found in Meta Business Suite or via `get_account_pages` tool
+- **Facebook Page** connected to your Instagram account
+- **Meta long-lived access token** (see setup guide below)
+- **Instagram Business Account ID** (obtained during setup)
 
+## Setup Guide — Getting Your Access Token
+
+Meta's token setup is a multi-step process. Follow these steps carefully.
+
+### Step 1: Connect Instagram to a Facebook Page
+
+Your IG Business/Creator account **must** be linked to a Facebook Page. Without this, the Graph API won't work.
+
+1. Open Instagram app → Settings → Account → Sharing to other apps → Facebook
+2. Select the Facebook Page to connect
+3. If you don't have a Page, create one at [facebook.com/pages/creation](https://www.facebook.com/pages/creation/)
+
+### Step 2: Create a Meta Developer App
+
+1. Go to [developers.facebook.com](https://developers.facebook.com) → Log in
+2. Click **"Create App"**
+3. App name: anything (e.g. "My IG Tool") — **cannot contain** "IG", "Instagram", "Facebook", etc.
+4. Use case: **"Manage Instagram content and messaging"** (under Content Management)
+5. Skip business portfolio for now
+6. Complete creation
+
+### Step 3: Add Permissions
+
+1. Go to your app → **Use Cases** → **Customize** → **API setup with Facebook login**
+2. Click **"Add required content permissions"** (adds `instagram_basic`, `instagram_content_publish`, `pages_read_engagement`, `business_management`, `pages_show_list`)
+3. Click **"Add required messaging permissions"** (adds `instagram_manage_messages`)
+
+### Step 4: Generate Access Token
+
+1. Go to [Graph API Explorer](https://developers.facebook.com/tools/explorer/)
+2. Select your app from the **"Meta App"** dropdown
+3. Click **"Get Token"** → **"Get User Access Token"**
+4. Add permissions: `instagram_basic`, `pages_show_list`, `pages_read_engagement`, `instagram_content_publish`, `instagram_manage_insights`, `instagram_manage_comments`
+5. Click **"Generate Access Token"** → Authorize in the popup
+6. Copy the token
+
+> **Note:** The Graph API Explorer may show "No configuration available" if permissions aren't set up yet. Make sure Step 3 is done first.
+
+### Step 5: Get Your Instagram Business Account ID
+
+In the Graph API Explorer, run:
+
+```
+GET /me/accounts?fields=id,name,instagram_business_account
+```
+
+Find your Page in the response. The `instagram_business_account.id` is your `INSTAGRAM_ACCOUNT_ID`.
+
+### Step 6: Exchange for Long-Lived Token (60 days)
+
+The token from Step 4 expires in 1 hour. Exchange it:
+
+```bash
+curl "https://graph.facebook.com/v19.0/oauth/access_token?\
+grant_type=fb_exchange_token&\
+client_id=YOUR_APP_ID&\
+client_secret=YOUR_APP_SECRET&\
+fb_exchange_token=YOUR_SHORT_LIVED_TOKEN"
+```
+
+Find your App ID and App Secret in: App Dashboard → Settings → Basic.
+
+The returned `access_token` is valid for 60 days.
+
+### Step 7: Configure and Run
+
+```bash
+export INSTAGRAM_ACCESS_TOKEN="your-long-lived-token"
+export INSTAGRAM_ACCOUNT_ID="your-ig-business-account-id"
+npx @mcpware/ig-mcp
+```
+
+### Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `me/accounts` returns empty `[]` | IG not connected to a Facebook Page, or you're not Page admin | Do Step 1 |
+| Graph API Explorer says "No configuration available" | Permissions not added to app | Do Step 3 |
+| "Generate Access Token" is disabled | Need to select "Get User Access Token" first | Click "Get Token" dropdown |
+| App name rejected (contains "IG", "Insta", etc.) | Meta blocks trademarked words | Use a generic name |
+| Token expired | Short-lived tokens last 1 hour | Do Step 6 for 60-day token |
+| `(#10) To use Instagram Graph API...` | IG account is Personal, not Business | Switch to Business/Creator in IG settings |
+
 ## Environment Variables
@@ -44,0 +128,0 @@

New alerts

Unpublished package

Supply chain risk

Package version was not found on the registry. It may exist on a different registry and need to be configured to pull from that registry.

Fixed alerts

Unpopular package

Quality

This package is not very popular.

Improved metrics

Total package byte prevSize

85328

4.49%

Number of medium quality alerts

0

-100%

Number of lines in readme file

197

74.34%

Worsened metrics

Number of medium supply chain risk alerts

3

50%

No dependency changes