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 一起创造精彩内容了吗？🎨✨