# Instagram MCP Server

A professional, well-structured MCP (Model Context Protocol) server for managing and posting Instagram content — PDF to images, carousel batches, auto-posting, and Cloudinary hosting.

## Features

- 📸 **Content management** — list, view, delete, archive local images
- ✏️ **Metadata** — captions & hashtags per content item
- 📱 **Post to Instagram** — single image or carousel posts via Graph API
- 🖼️ **PDF → Images** — convert PDF pages to PNGs (poppler)
- 🎠 **Carousel batches** — group images into 2-10 image carousels
- ☁️ **Cloudinary** — temporary image hosting + auto-cleanup
- 🔑 **Token diagnostics** — debug token expiry, scopes, and meta error codes

## Project Structure

```
instagram-mcp/
├── src/instagram_mcp/          # Main package
│   ├── config.py               # Env, constants, paths
│   ├── logging_setup.py        # Console + file logging
│   ├── errors.py               # Meta error parsing + guidance
│   ├── server.py               # FastMCP registration (thin)
│   ├── __main__.py             # python -m instagram_mcp
│   ├── services/               # External integrations
│   │   ├── instagram.py        #   Graph API client
│   │   ├── cloudinary.py       #   Upload/delete/verify
│   │   └── pdf.py              #   PDF → images
│   ├── storage/                # Local data access
│   │   ├── content.py          #   File resolution
│   │   └── metadata.py         #   JSON load/save
│   └── tools/                  # MCP tool implementations
│       ├── content_tools.py
│       ├── metadata_tools.py
│       ├── instagram_tools.py
│       ├── cloudinary_tools.py
│       └── carousel_tools.py
├── scripts/                    # CLI utilities
│   ├── check_token.py          #   Validate token + scopes
│   └── refresh_token.py        #   Extend long-lived token
├── tests/                      # pytest suite (mocked HTTP)
├── content/                    # Your media files (unchanged)
├── archive/                    # Archived content
├── logs/                       # Log files
├── server.py                   # Backward-compatible entry point
└── pyproject.toml              # Package config
```

## Installation

```bash
# Create & activate venv (Windows)
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install package (editable)
pip install -e .
```

## Configuration

Copy `.env.example` → `.env` and fill in:

```bash
# Instagram (required for posting)
INSTAGRAM_ACCESS_TOKEN=your_token_here
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_account_id_here

# Cloudinary (required for publish_image / carousels)
CLOUDINARY_CLOUD_NAME=...
CLOUDINARY_API_KEY=...
CLOUDINARY_API_SECRET=...

# Optional
INSTAGRAM_API_VERSION=v23.0
LOG_LEVEL=INFO
DELETE_LOCAL_AFTER_PUBLISH=false
```

## Running the Server

```bash
# Option 1: Backward-compatible (Claude Desktop config)
python server.py

# Option 2: As a package
python -m instagram_mcp

# Option 3: Console script (after pip install -e .)
instagram-mcp
```

## CLI Utilities

```bash
# Check your token's validity, expiry, and scopes
python scripts/check_token.py

# Info on refreshing a long-lived token (60 days)
python scripts/refresh_token.py
```

## Testing

```bash
pip install -e ".[dev]"
pytest
```

## MCP Tools

| Tool | Purpose |
|------|---------|
| `list_content` | List local images in content dir |
| `get_content` | Get file metadata (mime, size) |
| `manage_content` | list / delete / archive content |
| `manage_metadata` | Update / view / clear captions & hashtags |
| `test_instagram_connection` | Test Graph API connection |
| `debug_instagram_token` | Debug token expiry + scopes |
| `post_to_instagram` | Post single image (direct upload) |
| `test_cloudinary_upload` | Upload to Cloudinary, verify URL |
| `cleanup_cloudinary_asset` | Delete a Cloudinary asset |
| `publish_image` | Publish via Cloudinary HTTPS URL |
| `convert_pdf_to_images` | PDF → PNG images |
| `create_carousel_batch` | Group images into carousels |
| `post_carousel_to_instagram` | Post a carousel + auto-cleanup |
| `list_carousel_batches` | List carousels + status |

## Resource

- `instagram://content/{filename}` — access images as base64 blobs for visual analysis.

## Troubleshooting: Daily "API access blocked (code 200)"

Run `test_instagram_connection` and `debug_instagram_token` to diagnose.

Common causes & fixes:

1. **App in Development Mode** → switch to **Live** in Meta Developer dashboard.
2. **Missing approved permissions** → submit App Review for `instagram_basic` + `instagram_content_publish`.
3. **Token expired/revoked (60 days)** → generate a fresh long-lived token.
4. **App flagged by Meta** → check the app review status / appeal.

Logs are written to `logs/instagram_mcp.log` for diagnosis.