Aipic Mcp

AI Picture MCP Server

Webデザインのワークフロー向けに特化した、AI による画像生成機能を提供する Model Context Protocol（MCP）サーバーです。このサーバーは Alibaba Cloud DashScope の FLUX モデルと連携し、英語のプロンプトに基づいて高品質な画像を生成します。プレースホルダー画像、ヒーロー画像、製品のモックアップ、その他の Web アセットの作成に最適です。

🚀 クイックスタート

npx -y aipic-mcp

✨ 機能

• 🎨 AI 画像生成：自然言語のプロンプトを使用し、DashScope FLUX モデルで高品質な画像を生成します
• 🖥️ Web 向けに最適化された出力：適切な圧縮とサイズ設定により、Web での使用に合わせて画像を自動的に最適化します
• 📏 柔軟なサイズ指定：幅と高さをカスタム指定できます（デフォルト：1024x1024）
• 📋 Base64 エンコード：Web アプリケーションで直接使用できるよう、画像を Base64 形式で返します
• ⚡ スマートなファイル保存：可能な場合はデスクトップに自動保存し、保存できない場合は一時ディレクトリに保存します
• 🔄 非同期処理：信頼性の高い画像生成のため、DashScope の非同期タスク API を使用します
• 🛡️ 堅牢なエラー処理：API の問題、ネットワークの問題、無効な入力を包括的に処理します
• 🔐 環境変数のサポート：DASHSCOPE_API_KEY または MODELSCOPE_API_KEY で API キーを設定できます

📦 インストールと使用方法

オプション 1：NPX（推奨）

インストールせずに NPX から直接使用します。

npx -y aipic-mcp

Claude Desktop の設定：

{
  "mcpServers": {
    "aipic": {
      "command": "npx",
      "args": ["-y", "aipic-mcp"]
    }
  }
}

オプション 2：API キー環境変数を使用した NPX（推奨）

最適な使用体験のために、DashScope API キーを環境変数として設定します。

{
  "mcpServers": {
    "aipic": {
      "command": "npx",
      "args": ["-y", "aipic-mcp"],
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key-here"
      }
    }
  }
}

PATH をすべて指定する場合（NVM またはカスタムの Node インストールを使用している場合）：

{
  "mcpServers": {
    "aipic": {
      "command": "/Users/your-username/.nvm/versions/node/v20.19.4/bin/npx",
      "args": ["-y", "aipic-mcp"],
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key-here",
        "PATH": "/Users/your-username/.nvm/versions/node/v20.19.4/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

オプション 3：グローバルインストール

npm install -g aipic-mcp

Claude Desktop の設定：

{
  "mcpServers": {
    "aipic": {
      "command": "aipic-mcp"
    }
  }
}

API キー環境変数を使用する場合：

{
  "mcpServers": {
    "aipic": {
      "command": "aipic-mcp",
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key-here"
      }
    }
  }
}

オプション 4：ローカル開発

プロジェクトに貢献したい場合、またはカスタマイズしたい場合：

1. このリポジトリをクローンします：

git clone https://github.com/leonaries/aipic-mcp.git
cd aipic-mcp

2. 依存関係をインストールします：

npm install

3. TypeScript コードをビルドします：

npm run build

4. ローカルでテストします：

npm run dev

ローカル開発用の Claude Desktop 設定：

{
  "mcpServers": {
    "aipic": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/Users/your-username/path/to/aipic-mcp",
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key-here"
      }
    }
  }
}

注：/Users/your-username/path/to/aipic-mcp を、リポジトリをクローンした実際のパスに置き換えてください。

⚙️ 設定

Claude Desktop のセットアップ

Claude Desktop の設定ファイルにサーバーを追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

インストール方法に応じて、上記の設定オプションからいずれかを選択してください。

DashScope API キー

このサーバーを使用するには、Alibaba Cloud の DashScope API キーが必要です。Alibaba Cloud DashScope から取得してください。

API キーの取得方法：

1. Alibaba Cloud DashScope にアクセスします
2. アカウントに登録するか、ログインします
3. API Keys セクションに移動します
4. 画像生成権限を持つ新しい API キーを作成します
5. API キーをコピーします（形式：sk-xxxxxxxxxx）

API キーを指定する方法は 2 つあります：

1. 環境変数（推奨）：上記のとおり、Claude Desktop の設定で指定します
2. 実行時パラメーター：ツールを呼び出す際に API キーを渡します（利便性は低いものの、柔軟性があります）

🎯 使用方法

このサーバーは、1 つの主要なツールを提供します。

generate_web_image

Web デザイン用途に最適化された AI 画像を生成します。

パラメーター：

• prompt（必須）：生成する画像の英語での説明
• apiKey（任意）：DashScope API キー（DASHSCOPE_API_KEY 環境変数で設定されていない場合）
• width（任意）：画像の幅（ピクセル単位、デフォルト：1024）
• height（任意）：画像の高さ（ピクセル単位、デフォルト：1024）
• outputPath（任意）：画像を保存するカスタムパス（デフォルト：デスクトップまたは一時ディレクトリに自動保存）

プロンプトの例：

• 「ノートパソコンとコーヒーカップがある、モダンでミニマルなオフィスのワークスペース」
• 「青と紫のグラデーションを使った抽象的な幾何学模様の背景」
• 「明るい会議室でのプロフェッショナルなチームミーティング」
• 「白い背景にワイヤレスヘッドホンを配置した、E コマース用の商品写真」
• 「日の出時の山の風景を描いたヒーロー画像」

Claude での使用例（環境変数を設定済みの場合）：

Generate a hero image for my website with the prompt "A sleek modern smartphone floating above a city skyline at dusk"

Claude での使用例（API キーを手動で指定する場合）：

Generate a hero image for my website with the prompt "A sleek modern smartphone floating above a city skyline at dusk" using my DashScope API key "sk-your-api-key-here"

🔧 API 統合の詳細

このサーバーでは、以下の設定で Alibaba Cloud DashScope API を使用します。

• モデル：flux-schnell（高速生成用の FLUX.1 schnell モデル）
• エンドポイント：https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
• 認証：Bearer トークン（DashScope API キー）
• モード：タスクのポーリングを伴う非同期処理
• タイムアウト：生成は 5 分、ダウンロードは 30 秒

🛡️ エラー処理

サーバーは、以下のさまざまなエラー状況に対応します。

• 無効または未設定の API キー
• DashScope API によるレート制限
• ネットワークのタイムアウトや接続の問題
• タスクの生成失敗
• 画像のダウンロード失敗
• 画像の保存時に発生するファイルシステムのエラー

🔨 開発

開発モードでの実行

npm run dev

本番環境向けのビルド

npm run build

テスト

npm test

NPM への公開

このプロジェクトはすでに NPM で公開されています。メンテナー向けの手順：

npm run build
npm version patch  # or minor/major
npm publish

🤝 コントリビューション

コントリビューションを歓迎します！お気軽に Pull Request を送信してください。大規模な変更については、まず issue を作成し、変更したい内容について話し合ってください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/AmazingFeature）
3. 変更をコミットします（git commit -m 'Add some AmazingFeature'）
4. ブランチにプッシュします（git push origin feature/AmazingFeature）
5. Pull Request を作成します

🔒 セキュリティに関する考慮事項

• セキュリティを強化するため、環境変数で API キーを設定できます
• 画像は、現在の作業ディレクトリ内のローカルファイルシステムに保存されます
• 処理が停止しないよう、ネットワークリクエストには適切なタイムアウトが設定されています
• 入力検証により、空のプロンプトや必須パラメーターの不足を防止します
• 環境変数を使用する方が、キーをハードコードするよりも安全です

📚 依存関係

• @modelcontextprotocol/sdk：サーバー実装用の MCP SDK
• axios：API リクエスト用の HTTP クライアント
• sharp：画像処理と最適化
• uuid：ファイル名用の一意な ID の生成

🐛 トラブルシューティング

よくある問題

1. 「コマンドが見つかりません」というエラー

   • Node.js 18 以降がインストールされていることを確認してください。
   • グローバルインストールの代わりに、npx -y aipic-mcp を実行してみてください。
   • NVM を使用している場合は、設定で npx のフルパスを指定してください。

2. API キーのエラー

   • DashScope API キーが有効であることを確認してください（sk- で始まる必要があります）。
   • Alibaba Cloud アカウントに十分なクォータがあることを確認してください。
   • API キーが DASHSCOPE_API_KEY 環境変数として正しく設定されていることを確認してください。
   • API キーに画像生成の権限があることを確認してください。

3. 画像生成のタイムアウト

   • 複雑なプロンプトの場合、DashScope API の処理に最大 2～3 分かかることがあります。
   • よりシンプルなプロンプトで再試行してください。
   • インターネット接続を確認してください。

4. 環境変数が機能しない

   • 設定を更新した後、Claude Desktop を再起動してください。
   • 設定ファイルの JSON 構文を確認してください。
   • API キーに余分なスペースや引用符が含まれていないことを確認してください。

5. NPX のインストールに関する問題

   • インストールを自動的に確認するには、-y フラグを使用してください。
   • NVM を使用している場合は、設定で PATH が正しく設定されていることを確認してください。

6. タスク生成の失敗

   • サーバーは非同期処理を使用するため、完了まで少し時間がかかることがあります。
   • 詳細なエラーメッセージについては、コンソールログを確認してください。
   • 最良の結果を得るには、プロンプトを英語にしてください。

📄 ライセンス

MIT ライセンスです。詳細については LICENSE ファイルを参照してください。

🔗 リンク

• NPM パッケージ: https://www.npmjs.com/package/aipic-mcp
• GitHub リポジトリ: https://github.com/leonaries/aipic-mcp
• Alibaba Cloud DashScope: https://dashscope.aliyun.com/
• Model Context Protocol: https://modelcontextprotocol.io/

📝 変更履歴

v1.0.4（最新）

• 📝 ドキュメントの更新：機能の説明を強化し、README を大幅に改善しました。
• 🔧 API キーの形式：DashScope API キーの正しい sk- プレフィックスを使用するよう、すべての例を更新しました。
• 🌐 環境変数：従来の MODELSCOPE_API_KEY よりも DASHSCOPE_API_KEY を優先して使用することを明確にしました。
• ✨ ユーザーエクスペリエンス：インストールガイドとトラブルシューティングのドキュメントを改善しました。

v1.0.3

• ⚡ スマートなファイル保存：可能な場合は画像をデスクトップに自動保存し、できない場合は一時ディレクトリに保存します。
• 🔧 環境変数の強化：DASHSCOPE_API_KEY を優先してサポートし、MODELSCOPE_API_KEY との後方互換性も維持します。
• 🛡️ エラー処理の改善：エラーメッセージを改善し、API 統合の堅牢性を高めました。
• 📁 インテリジェントなパス検出：ディレクトリの自動作成とフォールバックの仕組みを追加しました。
• 🚀 ユーザーエクスペリエンスの向上：画像はデフォルトでユーザーのデスクトップに直接保存されるようになりました。

v1.0.1

• 🔧 破壊的変更：ModelScope API の代わりに Alibaba Cloud DashScope API を使用するよう更新しました。
• ✨ より信頼性の高い画像生成のため、非同期タスク処理を追加しました。
• 🐛 API 認証の問題を修正しました。
• 📚 DashScope との統合を反映するよう、ドキュメントを更新しました。

v1.0.0

• 🎉 ModelScope との統合による初回リリース

---

🌟 役に立った場合は、このリポジトリにスターを付けてください！