Freepik MCP

🚀 Freepik FastMCP 工具包

Freepik FastMCP 工具包是一個 Model Context Protocol (MCP) 服務器，它能將你的 AI 助手（如 Claude、Cursor 等）直接與 Freepik 強大的 API 連接起來。讓你無需離開 AI 工作流程，就能生成、搜索和管理視覺內容。

🚀 快速開始

本工具包是一個 Model Context Protocol (MCP) 服務器，它能將你的 AI 助手（Claude、Cursor 等）直接與 Freepik 強大的 API 連接起來。讓你無需離開 AI 工作流程，就能生成、搜索和管理視覺內容。

✨ 主要特性

• 🎨 圖標搜索與下載 - 查找並下載多種格式的圖標
• 📁 資源管理 - 訪問和管理多媒體內容
• 🤖 AI 圖像分類 - 自動對圖像進行分類和分析
• 🖼️ 圖像生成 - 使用 Mystic AI 創建自定義圖像

📦 安裝指南

前提條件

在開始之前，請確保你已經具備以下條件：

• 安裝了 Python 3.12+
• 安裝了 uv 依賴管理器（點擊此處安裝）
• 擁有 Freepik API 密鑰（點擊此處獲取）

安裝步驟

1. 克隆倉庫並進入目錄

git clone <REPOSITORY_URL>
cd freepik-toolkit/fastmcp

2. 使用 Makefile 進行安裝

# 安裝依賴
make install

# 驗證安裝
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 系統，需要使用 WSL（Windows Subsystem for Linux）來運行此 MCP 服務器。

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

重要配置步驟

1. 查找完整路徑：

   pwd
   # 複製輸出內容，並替換配置文件中的 /FULL/PATH/TO/
   

2. 替換為你的 API 密鑰：

   • 從 freepik.com/api 獲取 API 密鑰。
   • 替換 your_actual_api_key_here。

🏃‍♂️ 快速啟動

# 開發模式（自動重新加載）
make dev

# 生產模式
make run

# 檢查代碼質量
make lint

# 格式化代碼
make format

# 清理臨時文件
make clean

# 查看所有命令
make help

🤝 貢獻代碼

我們歡迎你的貢獻！請遵循以下指南：

📝 提交規範

本項目使用 Conventional Commits。提交信息的格式如下：

<類型>(<範圍>): <描述>

[可選的正文]

[可選的腳註]

類型說明：

• feat：新特性
• fix：修復 bug
• 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 上創建一個問題，並提供以下信息：

• 你的操作系統和 Python 版本
• 完整的錯誤信息
• 配置文件（不包含 API 密鑰）

準備好與 AI 一起創造精彩內容了嗎？🎨✨