Freepik MCP

🚀 用于无缝集成 Freepik API 的 MCP 服务器

🎯 这是什么？

一个 模型上下文协议 (MCP) 服务器，可将您的 AI 助手（Claude、Cursor 等）直接与 Freepik 强大的 API 连接起来。无需离开 AI 工作流即可生成、搜索和管理视觉内容。

🛠️ 有哪些可用工具？

• 🎨 图标搜索与下载 - 以多种格式查找并下载图标

• 📁 资源管理 - 访问和管理多媒体内容

• 🤖 AI 图像分类 - 自动分类和分析图像

• 🖼️ 图像生成 - 使用 Mystic AI 创建自定义图像

📋 前置要求

在开始之前，请确保您已具备：

• 已安装 Python 3.12+

• uv 依赖管理器 (点击此处安装)

• Freepik API Key (在此获取)

🚀 安装

1. 克隆并进入目录

git clone <REPOSITORY_URL>
cd freepik-mcp

2. 使用 Makefile 安装

# Install dependencies
make install

# Verify installation
make version

3. 配置您的 API Key

echo "FREEPIK_API_KEY=your_api_key_here" > .env

💡 在此获取您的 API Key： freepik.com/api

⚙️ AI 助手配置

适用于 Linux 上的 Claude Desktop 或 Cursor

将此内容添加到您的 config.json 文件中：

⚠️ Windows 用户注意： 如果您使用的是 Windows，则需要使用 WSL（Windows Linux 子系统）来运行此 MCP 服务器。

{
  "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 Key：

   • 从 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. 发起 Pull Request

📚 开发命令

🛡️ 安全性

• ⚠️ 切勿提交您的 API Key

• ✅ 使用 .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，并提供：

• 您的操作系统和 Python 版本

• 完整的错误消息

• 配置文件（不含 API Key）

准备好用 AI 创作惊人的内容了吗？ 🎨✨