Freepik MCP

🚀 Freepik APIをシームレスに統合するためのMCPサーバー

🎯 これは何ですか？

AIアシスタント（Claude、Cursorなど）をFreepikの強力なAPIに直接接続するModel Context Protocol (MCP) サーバーです。AIワークフローを離れることなく、ビジュアルコンテンツの生成、検索、管理が行えます。

🛠️ 利用可能なツール

• 🎨 アイコン検索・ダウンロード - 複数の形式でアイコンを検索・ダウンロード

• 📁 リソース管理 - マルチメディアコンテンツへのアクセスと管理

• 🤖 AI画像分類 - 画像の自動分類と分析

• 🖼️ 画像生成 - Mystic AIを使用したカスタム画像の作成

📋 前提条件

開始する前に、以下が準備されていることを確認してください：

• Python 3.12+ がインストールされていること

• uv パッケージマネージャー (インストールはこちら)

• Freepik APIキー (取得はこちら)

🚀 インストール

1. クローンしてディレクトリに移動

git clone <REPOSITORY_URL>
cd freepik-mcp

2. Makefileを使用してインストール

# Install dependencies
make install

# Verify installation
make version

3. APIキーの設定

echo "FREEPIK_API_KEY=your_api_key_here" > .env

💡 APIキーの取得先: freepik.com/api

⚙️ AIアシスタントの設定

Linux上のClaude DesktopまたはCursorの場合

config.jsonファイルに以下を追加します：

⚠️ Windowsユーザーの方へ: WindowsでこのMCPサーバーを実行するには、WSL (Windows Subsystem for Linux) を使用する必要があります。

{
  "mcpServers": {
    "freepik-fastmcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/FULL/PATH/TO/freepik-mcp",
        "main.py"
      ],
      "env": {
        "FREEPIK_API_KEY": "your_actual_api_key_here"
      }
    }
  }
}

🔧 重要な設定手順

1. フルパスを確認する:

   pwd
   # Copy the output and replace /FULL/PATH/TO/ in the config

2. APIキーを置き換える:

   • freepik.com/api から取得してください

   • your_actual_api_key_here を置き換えてください

🏃♂️ クイックスタート

# Development mode (auto-reload)
make dev

# Production mode
make run

# Check code quality
make lint

# Format code
make format

# Clean temporary files
make clean

# See all commands
make help

🤝 コントリビューション

コントリビューションを歓迎します！以下のガイドラインに従ってください：

📝 コミット規約

このプロジェクトでは Conventional Commits を使用しています。コミットメッセージは以下の形式で記述してください：

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

タイプ:

• feat: 新機能

• fix: バグ修正

• docs: ドキュメントの変更

• style: コードスタイルの変更（フォーマットなど）

• refactor: コードのリファクタリング

• test: テストの追加または更新

• chore: メンテナンス作業

例:

feat(icons): add search filtering by category
fix(api): resolve authentication timeout issue
docs(readme): update installation instructions
refactor(mystic): improve error handling logic

🔄 コントリビューションの流れ

1. リポジトリを Fork する

2. フィーチャーブランチを 作成 する: git checkout -b feat/amazing-feature

3. 規約に従って コミット する: git commit -m "feat: add amazing feature"

4. ブランチに プッシュ する: git push origin feat/amazing-feature

5. プルリクエストを 作成 する

📚 開発コマンド

🛡️ セキュリティ

• ⚠️ APIキーをコミットしないでください

• ✅ 機密データには .env ファイルを使用してください

• ✅ .env ファイルは .gitignore に含まれています

📖 APIドキュメント

詳細なAPI情報については以下を参照してください：

• Freepik APIドキュメント

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

よくある問題:

1. "Command not found" → uv パッケージマネージャーをインストールしてください

2. "Invalid API Key" → freepik.com/api でキーを確認してください

3. "Path not found" → 設定内のフルパスを確認してください

4. "Connection refused" → make dev でサーバーが実行されていることを確認してください

それでも問題が解決しない場合: GitHubでIssueを作成してください。その際、以下を含めてください：

• OSとPythonのバージョン

• 完全なエラーメッセージ

• 設定ファイル（APIキーは除外してください）

AIで素晴らしいコンテンツを作成する準備はできましたか？ 🎨✨