instagram-mcp-server 1.6.6

package/.env.example

@@ -0,0 +1,2 @@
+INSTAGRAM_ACCESS_TOKEN=your_long_lived_facebook_page_token_here
+INSTAGRAM_BUSINESS_ACCOUNT_ID=your_17_digit_ig_business_account_id

package/.github/dependabot.yml

@@ -0,0 +1,50 @@
+version: 2
+updates:
+  # npm dependencies
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      dev-dependencies:
+        patterns:
+          - "typescript"
+          - "tsx"
+          - "vitest"
+          - "@types/*"
+          - "prettier"
+        update-types:
+          - "minor"
+          - "patch"
+      runtime-dependencies:
+        patterns:
+          - "@modelcontextprotocol/*"
+          - "zod"
+        update-types:
+          - "patch"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"

package/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test-matrix:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ["20", "22"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Format check with prettier
+        run: npx prettier --check .
+
+      - name: Type check with tsc
+        run: npx tsc --noEmit
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+  test:
+    needs: [test-matrix]
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Check test matrix status
+        run: |
+          if [ "${{ needs.test-matrix.result }}" != "success" ]; then
+            echo "Test matrix failed with result: ${{ needs.test-matrix.result }}"
+            exit 1
+          fi
+          echo "All tests passed!"

package/.github/workflows/release.yml

@@ -0,0 +1,200 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Check for skip-release marker
+        id: check_skip
+        run: |
+          SUBJECT=$(git log -1 --pretty=%s)
+          if echo "$SUBJECT" | grep -q '\[skip-release\]'; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+            echo "Skipping release: $SUBJECT"
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+            echo "Proceeding with release check: $SUBJECT"
+          fi
+
+      - name: Set up Node.js
+        if: steps.check_skip.outputs.skip != 'true'
+        uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+          cache: "npm"
+
+      - name: Install dependencies
+        if: steps.check_skip.outputs.skip != 'true'
+        run: npm ci
+
+      - name: Run tests
+        if: steps.check_skip.outputs.skip != 'true'
+        run: npm test
+
+      - name: Build
+        if: steps.check_skip.outputs.skip != 'true'
+        run: npm run build
+
+      - name: Configure Git
+        if: steps.check_skip.outputs.skip != 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Determine next version
+        id: version
+        if: steps.check_skip.outputs.skip != 'true'
+        run: |
+          CURRENT_VERSION=$(node -p "require('./package.json').version")
+          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+
+          echo "current_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+
+          if [ -z "$LAST_TAG" ]; then
+            echo "new_release=true" >> $GITHUB_OUTPUT
+            echo "new_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+            echo "bump=initial" >> $GITHUB_OUTPUT
+            echo "First release: $CURRENT_VERSION"
+            exit 0
+          fi
+
+          COMMITS=$(git log "$LAST_TAG"..HEAD --pretty=%s)
+
+          if [ -z "$COMMITS" ]; then
+            echo "No new commits since $LAST_TAG"
+            echo "new_release=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          BUMP=""
+          if echo "$COMMITS" | grep -qiE '^[a-z]+(\(.+\))?!:|BREAKING CHANGE'; then
+            BUMP="major"
+          elif echo "$COMMITS" | grep -qiE '^feat(\(.+\))?:'; then
+            BUMP="minor"
+          elif echo "$COMMITS" | grep -qiE '^(fix|perf|refactor)(\(.+\))?:'; then
+            BUMP="patch"
+          fi
+
+          if [ -z "$BUMP" ]; then
+            echo "No release-worthy commits (feat/fix/perf/refactor) since $LAST_TAG"
+            echo "new_release=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
+          case "$BUMP" in
+            major) MAJOR=$((MAJOR + 1)); MINOR=0; PATCH=0 ;;
+            minor) MINOR=$((MINOR + 1)); PATCH=0 ;;
+            patch) PATCH=$((PATCH + 1)) ;;
+          esac
+          NEW_VERSION="$MAJOR.$MINOR.$PATCH"
+
+          echo "new_release=true" >> $GITHUB_OUTPUT
+          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          echo "bump=$BUMP" >> $GITHUB_OUTPUT
+          echo "Detected $BUMP bump: $CURRENT_VERSION → $NEW_VERSION"
+
+      - name: Bump version in package.json
+        if: steps.version.outputs.new_release == 'true'
+        run: |
+          if [ "${{ steps.version.outputs.bump }}" = "initial" ]; then
+            git tag -a "v${{ steps.version.outputs.new_version }}" -m "Release v${{ steps.version.outputs.new_version }}"
+          else
+            npm version ${{ steps.version.outputs.new_version }} --no-git-tag-version
+            git add package.json package-lock.json
+            git commit -m "chore(release): ${{ steps.version.outputs.new_version }} [skip-release]"
+            git tag -a "v${{ steps.version.outputs.new_version }}" -m "Release v${{ steps.version.outputs.new_version }}"
+          fi
+
+      - name: Push version commit and tag
+        if: steps.version.outputs.new_release == 'true'
+        run: |
+          git push origin main --follow-tags
+
+      - name: Generate release notes
+        id: notes
+        if: steps.version.outputs.new_release == 'true'
+        run: |
+          LAST_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "")
+          NEW_VERSION="v${{ steps.version.outputs.new_version }}"
+
+          {
+            echo "notes<<RELEASE_NOTES_EOF"
+
+            if [ -n "$LAST_TAG" ]; then
+              echo "## What's Changed"
+              echo ""
+
+              FEATS=$(git log "$LAST_TAG"..HEAD~1 --pretty="- %s" | grep -iE '^\- feat' || true)
+              FIXES=$(git log "$LAST_TAG"..HEAD~1 --pretty="- %s" | grep -iE '^\- fix' || true)
+              OTHERS=$(git log "$LAST_TAG"..HEAD~1 --pretty="- %s" | grep -viE '^\- (feat|fix|chore\(release\))' || true)
+
+              if [ -n "$FEATS" ]; then
+                echo "### Features"
+                echo "$FEATS"
+                echo ""
+              fi
+              if [ -n "$FIXES" ]; then
+                echo "### Bug Fixes"
+                echo "$FIXES"
+                echo ""
+              fi
+              if [ -n "$OTHERS" ]; then
+                echo "### Other Changes"
+                echo "$OTHERS"
+                echo ""
+              fi
+
+              echo "**Full Changelog**: https://github.com/${{ github.repository }}/compare/$LAST_TAG...$NEW_VERSION"
+            else
+              echo "Initial release"
+            fi
+
+            echo "RELEASE_NOTES_EOF"
+          } >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        if: steps.version.outputs.new_release == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          gh release create "v${{ steps.version.outputs.new_version }}" \
+            --title "v${{ steps.version.outputs.new_version }}" \
+            --notes "${{ steps.notes.outputs.notes }}" \
+            --latest
+
+      - name: Publish to npm
+        if: steps.version.outputs.new_release == 'true'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          npm publish
+
+      - name: Release summary
+        if: steps.version.outputs.new_release == 'true'
+        run: |
+          echo "## Release Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Released version: **v${{ steps.version.outputs.new_version }}** (${{ steps.version.outputs.bump }} bump)" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Published to:" >> $GITHUB_STEP_SUMMARY
+          echo "- GitHub Releases" >> $GITHUB_STEP_SUMMARY
+          echo "- npm (npx installable)" >> $GITHUB_STEP_SUMMARY

package/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Thanks for your interest in contributing to Instagram MCP Server!
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/your-username/instagram-mcp-server.git`
+3. Install dependencies: `npm install`
+4. Create a feature branch: `git checkout -b feat/my-feature`
+
+## Development
+
+```bash
+npm run dev      # Run with tsx (hot reload)
+npm run build    # Compile TypeScript
+npm test         # Run tests
+```
+
+## Pull Requests
+
+- Keep PRs focused on a single change
+- Add tests for new functionality
+- Make sure `npm test` and `npm run build` pass
+- Use clear, descriptive commit messages
+
+## Reporting Issues
+
+Open an issue with:
+
+- What you expected to happen
+- What actually happened
+- Steps to reproduce
+- Node.js version and OS
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Luminary Lane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Makefile

@@ -0,0 +1,16 @@
+.PHONY: install build dev test clean
+
+install:
+	npm install
+
+build:
+	npm run build
+
+dev:
+	npm run dev
+
+test:
+	npm test
+
+clean:
+	rm -rf dist node_modules

package/README.md

@@ -0,0 +1,141 @@
+# Instagram MCP Server
+
+[![MCP](https://img.shields.io/badge/MCP-1.0-blue)](https://modelcontextprotocol.io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org)
+[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
+
+A Model Context Protocol (MCP) server that connects Claude Desktop (and other MCP clients) to the Instagram Graph API — read analytics, manage comments, publish photos, carousels, and reels.
+
+## Features
+
+### 11 Instagram Tools
+
+**SENSE (read-only):**
+| Tool | Description |
+|------|-------------|
+| `ig_get_account_insights` | Account insights: reach, follower growth, profile views over a period |
+| `ig_get_post_insights` | Engagement metrics for a specific post: reach, likes, shares, saves |
+| `ig_get_comments` | Comments on a post with username, timestamp, and replies |
+| `ig_get_stories_insights` | Insights for an active story: reach, replies, interactions |
+| `ig_get_audience_demographics` | Follower demographics: city, country, age/gender breakdown |
+| `ig_get_hashtag_search` | Search public posts by hashtag (30 unique hashtags per 7-day window) |
+
+**ACT (write):**
+| Tool | Description |
+|------|-------------|
+| `ig_publish_photo` | Publish a photo post from a public URL |
+| `ig_publish_carousel` | Publish a carousel (2-10 images) from public URLs |
+| `ig_publish_reel` | Publish a reel (short video) from a public URL |
+| `ig_reply_comment` | Reply to a comment on a post |
+| `ig_delete_comment` | Delete a comment on one of your posts |
+
+### Built-in Reliability
+
+- **Per-tenant rate limiting** — token-bucket rate limiter keyed by IG Business Account ID
+- **Exponential backoff retry** — automatic retry with jitter for transient API errors
+- **Container-based publishing** — create container → poll status → publish (handles async video processing)
+- **Input sanitization** — strips zero-width characters, normalizes whitespace, truncates to API limits
+- **Prompt injection protection** — wraps external API data in randomized markers
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+
+- An Instagram Business or Creator account connected to a Facebook Page
+- A Facebook App with the Instagram Graph API enabled
+- A long-lived Page Access Token
+
+### Getting Your Access Token
+
+1. Create a [Facebook App](https://developers.facebook.com/apps/)
+2. Add the **Instagram Graph API** product
+3. In [Graph API Explorer](https://developers.facebook.com/tools/explorer/), generate a Page Access Token with these permissions:
+   - `instagram_basic`, `instagram_content_publish`, `instagram_manage_comments`, `instagram_manage_insights`, `pages_show_list`, `pages_read_engagement`
+4. [Extend the token](https://developers.facebook.com/tools/debug/accesstoken/) to a long-lived token (60 days)
+
+### Installation
+
+```bash
+git clone https://github.com/luminarylane/instagram-mcp-server.git
+cd instagram-mcp-server
+npm install
+npm run build
+```
+
+### Configuration
+
+**Claude Desktop (`claude_desktop_config.json`):**
+
+```json
+{
+  "mcpServers": {
+    "instagram": {
+      "command": "node",
+      "args": ["/path/to/instagram-mcp-server/dist/index.js"],
+      "env": {
+        "INSTAGRAM_ACCESS_TOKEN": "your_long_lived_page_token",
+        "INSTAGRAM_BUSINESS_ACCOUNT_ID": "your_17_digit_ig_business_account_id"
+      }
+    }
+  }
+}
+```
+
+**Environment variables:**
+
+| Variable                        | Required | Description                           |
+| ------------------------------- | -------- | ------------------------------------- |
+| `INSTAGRAM_ACCESS_TOKEN`        | Yes\*    | Long-lived Facebook Page Access Token |
+| `INSTAGRAM_BUSINESS_ACCOUNT_ID` | Yes\*    | 17-digit IG Business Account ID       |
+
+\*Can also be passed per-call via tool arguments.
+
+### Finding Your Business Account ID
+
+Use the Graph API Explorer:
+
+```
+GET /me/accounts?fields=instagram_business_account
+```
+
+The `instagram_business_account.id` field is your Business Account ID.
+
+## Usage Examples
+
+Once configured, ask Claude to:
+
+- "Show me my Instagram account insights for the last 28 days"
+- "What are the engagement metrics for my latest post?"
+- "Get the comments on this post" (paste a media ID)
+- "Show my follower demographics by country"
+- "Publish this photo to Instagram" (provide a public image URL + caption)
+- "Create a carousel post with these images"
+- "Reply to this comment with 'Thanks!'"
+- "Search recent posts with #startup"
+
+## Publishing
+
+Photo and carousel publishing is synchronous — the tool returns once the post is live. Reel publishing is asynchronous — the server polls the container status until processing completes, then publishes.
+
+All publish tools accept an optional `firstComment` parameter to add a comment immediately after publishing (commonly used for hashtags).
+
+## Rate Limiting
+
+The server enforces per-account rate limits to stay within Instagram's API quotas. If you hit a rate limit, the tool will return an error with a suggested retry time. The built-in retry logic handles transient 429 responses automatically.
+
+## Contributing
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Make changes and run tests (`npm test`)
+4. Submit a pull request
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+- [Anthropic](https://anthropic.com) for the MCP specification
+- [Meta Graph API](https://developers.facebook.com/docs/instagram-api/) for the underlying Instagram API

package/dist/client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Instagram Graph API client.
+ *
+ * Raw fetch wrapper against https://graph.instagram.com/v22.0/.
+ * No SDK — keeps dependencies minimal (Occam's Razor).
+ * Client instances are cached by credential hash.
+ */
+export interface Credentials {
+    accessToken: string;
+    accountId: string;
+}
+/**
+ * Get or create a cached Instagram client.
+ */
+export declare function createClient(creds: Credentials): InstagramClient;
+/**
+ * Graph API error format from Facebook/Instagram.
+ */
+export interface GraphApiError {
+    error: {
+        message: string;
+        type: string;
+        code: number;
+        error_subcode?: number;
+        fbtrace_id?: string;
+    };
+}
+/**
+ * Error thrown for Graph API failures. Carries structured error data
+ * for suggestAction() to inspect.
+ */
+export declare class InstagramApiError extends Error {
+    readonly status: number;
+    readonly code: number;
+    readonly errorSubcode?: number;
+    readonly errorType: string;
+    readonly retryAfter?: number;
+    constructor(status: number, apiError: GraphApiError["error"], retryAfter?: number);
+}
+export declare class InstagramClient {
+    readonly accessToken: string;
+    readonly accountId: string;
+    constructor(creds: Credentials);
+    /**
+     * Make a GET request to the Graph API.
+     */
+    get<T = unknown>(path: string, params?: Record<string, string>): Promise<T>;
+    /**
+     * Make a POST request to the Graph API.
+     */
+    post<T = unknown>(path: string, body?: Record<string, unknown>): Promise<T>;
+    /**
+     * Make a DELETE request to the Graph API.
+     */
+    delete<T = unknown>(path: string): Promise<T>;
+    private handleResponse;
+}