金大哥 - freepik-mcp MCP 详情

article

README

🚀 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"
      }
    }
  }
}

重要配置步骤

查找完整路径：

pwd
# 复制输出内容，并替换配置文件中的 /FULL/PATH/TO/

替换为你的 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

🔄 贡献工作流程

Fork 仓库
创建功能分支：git checkout -b feat/amazing-feature
提交遵循规范格式的代码：git commit -m "feat: add amazing feature"
推送到你的分支：git push origin feat/amazing-feature
打开拉取请求

📚 开发命令

| 命令 | 描述 | |---------|-------------| | make help | 显示所有可用命令 | | make install | 安装依赖 | | make dev | 以开发模式运行 | | make run | 以生产模式运行 | | make lint | 检查代码质量 | | make format | 自动格式化代码 | | make clean | 清理临时文件 | | make version | 检查 FastMCP 版本 |

🛡️ 安全提示

⚠️ 重要提示

切勿提交你的 API 密钥。

💡 使用建议

使用 .env 文件来存储敏感数据，并且 .env 文件已添加到 .gitignore 中。

📖 API 文档

如需详细的 API 信息，请访问：Freepik API 文档

🆘 故障排除

常见问题及解决方法

“Command not found” → 安装 uv 依赖管理器
“Invalid API Key” → 到 freepik.com/api 检查你的密钥
“Path not found” → 验证配置文件中的完整路径
“Connection refused” → 确保使用 make dev 启动服务器

仍有问题？

如果你仍然遇到问题，请在 GitHub 上创建一个问题，并提供以下信息：

你的操作系统和 Python 版本
完整的错误信息
配置文件（不包含 API 密钥）

freepik-mcp