# Instagram MCP Server 📸

Instagram API を利用した MCP (Model Context Protocol) サーバー

## 概要

EnsembleData の Instagram API を使用して、Instagram のユーザー情報や投稿データを取得できる MCP サーバーです。Claude Desktop と統合することで、Claude に Instagram データへのアクセス機能を追加できます。

## 主な機能 ✨

### ユーザー情報
- ✅ ユーザー基本情報取得
- ✅ ユーザー詳細統計
- ✅ フォロワー数取得

### 投稿データ
- ✅ ユーザー投稿一覧
- ✅ リール（短尺動画）取得
- ✅ 投稿詳細情報とコメント

### 検索
- ✅ ユーザー検索
- ✅ ハッシュタグ検索
- ✅ 場所検索

## 必要要件 📋

### API キー
- [EnsembleData](https://ensembledata.com/) の API キーが必要です
- 無料プランでも利用可能（制限あり）

### システム要件
- Python 3.10 以上
- Claude Desktop アプリ
- インターネット接続

## インストール方法 🚀

### 自動インストール（推奨）

#### macOS / Linux
```bash
curl -sSf https://raw.githubusercontent.com/Readify-App/insta-mcp-server/main/install.sh | bash
```

または、リポジトリをクローンして実行:
```bash
git clone https://github.com/Readify-App/insta-mcp-server.git
cd insta-mcp-server
chmod +x install.sh
./install.sh
```

#### Windows (PowerShell)
```powershell
irm https://raw.githubusercontent.com/Readify-App/insta-mcp-server/main/install.ps1 | iex
```

または、リポジトリをクローンして実行:
```powershell
git clone https://github.com/Readify-App/insta-mcp-server.git
cd insta-mcp-server
.\install.ps1
```

### 手動インストール

1. **リポジトリのクローン**
```bash
git clone https://github.com/Readify-App/insta-mcp-server.git
cd insta-mcp-server
```

2. **依存関係のインストール**
```bash
uv sync
```

3. **Claude Desktop の設定**

`claude_desktop_config.json` に以下を追加:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "insta-mcp-server": {
      "command": "uv",
      "args": ["--directory", "/path/to/insta-mcp-server", "run", "insta-mcp-server"]
    }
  }
}
```

## 設定 ⚙️

### API キーの設定

インストール後、`server.py` を編集して API キーを設定してください:

```python
# server.py の該当箇所
API_KEY = "YOUR_API_KEY_HERE"  # ここに実際のAPIキーを設定
```

**推奨**: 環境変数を使用する方法
```python
import os
API_KEY = os.getenv("ENSEMBLEDATA_API_KEY", "YOUR_API_KEY_HERE")
```

環境変数で設定する場合:
```bash
# ~/.zshrc または ~/.bashrc に追加
export ENSEMBLEDATA_API_KEY="your_api_key_here"
```

## 使い方 📖

Claude Desktop を再起動後、以下のような質問ができます:

### ユーザー情報の取得
```
@instagram のユーザー情報を教えて
```

### 投稿の取得
```
@natgeo の最新の投稿を10件取得して
```

### リールの取得
```
@cristiano のリールを見せて
```

### ユーザー検索
```
Instagramで "travel" で検索して
```

### 投稿詳細の取得
```
この投稿の詳細を教えて: https://instagram.com/p/xxxxx
```

### フォロワー数の確認
```
@nike のフォロワー数は？
```

## 利用可能なツール 🛠️

### 1. instagram_user_info
ユーザーの基本情報を取得

**パラメータ:**
- `username` (str): Instagramユーザー名（@なし）

**使用例:**
```python
instagram_user_info(username="instagram")
```

### 2. instagram_user_posts
ユーザーの投稿一覧を取得

**パラメータ:**
- `username` (str): Instagramユーザー名（@なし）
- `count` (int): 取得する投稿数（デフォルト: 12）

**使用例:**
```python
instagram_user_posts(username="natgeo", count=20)
```

### 3. instagram_user_stats
ユーザーの統計情報を取得

**パラメータ:**
- `username` (str): Instagramユーザー名（@なし）

**使用例:**
```python
instagram_user_stats(username="cristiano")
```

### 4. instagram_user_reels
ユーザーのリールを取得

**パラメータ:**
- `username` (str): Instagramユーザー名（@なし）
- `count` (int): 取得するリール数（デフォルト: 12）

**使用例:**
```python
instagram_user_reels(username="redbull", count=10)
```

### 5. instagram_search
ユーザーやハッシュタグを検索

**パラメータ:**
- `query` (str): 検索キーワード
- `search_type` (str): 検索タイプ（"users", "hashtags", "places"）

**使用例:**
```python
instagram_search(query="travel", search_type="users")
```

### 6. instagram_post_info
投稿の詳細情報とコメントを取得

**パラメータ:**
- `post_url` (str): Instagram投稿のURL

**使用例:**
```python
instagram_post_info(post_url="https://instagram.com/p/xxxxx")
```

### 7. instagram_follower_count
フォロワー数を取得

**パラメータ:**
- `username` (str): Instagramユーザー名（@なし）

**使用例:**
```python
instagram_follower_count(username="nike")
```

## トラブルシューティング 🔧

### Claude Desktop に表示されない

1. **Claude Desktop を完全に再起動**
   - アプリを終了して再度起動してください

2. **設定ファイルを確認**
   ```bash
   # macOS
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Windows
   type %APPDATA%\Claude\claude_desktop_config.json
   ```

3. **パスが正しいか確認**
   - `claude_desktop_config.json` 内のパスが実際のインストールディレクトリと一致しているか確認

### API エラーが発生する

1. **API キーを確認**
   - `server.py` 内の `API_KEY` が正しく設定されているか確認

2. **API 制限を確認**
   - [EnsembleData ダッシュボード](https://ensembledata.com/dashboard) で使用量を確認

3. **ログを確認**
   ```bash
   # macOS/Linux
   tail -f /tmp/insta-mcp-server/debug.log
   
   # Windows
   type %TEMP%\insta-mcp-server\debug.log
   ```

### インストールスクリプトが失敗する

1. **必要なツールがインストールされているか確認**
   - curl, git, uv

2. **インターネット接続を確認**

3. **手動インストールを試す**
   - 上記の「手動インストール」セクションを参照

## 開発者向け情報 👨‍💻

### プロジェクト構造
```
insta-mcp-server/
├── README.md           # このファイル
├── install.ps1         # Windows用インストールスクリプト
├── install.sh          # Mac/Linux用インストールスクリプト
├── main.py             # エントリーポイント（固定）
├── pyproject.toml      # プロジェクト設定
└── server.py           # メインサーバー実装
```

### ローカル開発

1. **仮想環境の作成**
```bash
uv sync
```

2. **サーバーの起動**
```bash
uv run insta-mcp-server
```

3. **テスト**
```bash
# MCP Inspector を使用してテスト
npx @modelcontextprotocol/inspector uv --directory /path/to/insta-mcp-server run insta-mcp-server
```

### カスタマイズ

`server.py` を編集することで、以下のカスタマイズが可能です:

- 新しいツールの追加
- レスポンスフォーマットの変更
- エラーハンドリングの改善
- ログレベルの調整

## ライセンス 📄

MIT License

## サポート 💬

問題が発生した場合:

1. [Issues](https://github.com/Readify-App/insta-mcp-server/issues) で既存の問題を確認
2. 新しい Issue を作成
3. ログファイルを添付すると解決が早まります

## 謝辞 🙏

- [EnsembleData](https://ensembledata.com/) - Instagram API の提供
- [Anthropic](https://www.anthropic.com/) - Claude と MCP の開発
- [MCP Community](https://github.com/modelcontextprotocol) - プロトコルの開発とサポート

## 関連リンク 🔗

- [EnsembleData API ドキュメント](https://ensembledata.com/apis/docs)
- [MCP 公式ドキュメント](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/download)

---

**注意**: このツールは教育目的で作成されています。Instagram の利用規約を遵守し、APIの使用制限を守って使用してください。