Cursor + Flux 构建高质量本地运行的文生图 MCP 服务

推荐语

探索本地高效运行文生图服务的新路径。

核心内容：
1. 利用Cursor IDE和Flux模型搭建文生图服务
2. Flux系列模型特性与应用场景解析
3. 实施流程与环境配置要点

杨芳贤

53A创始人/腾讯云(TVP)最具价值专家

见字如面，与大家分享实践中的经验与思考。

在AI图像生成领域快速发展的今天，如何在本地环境搭建稳定高效的文生图服务成为了开发者关注的焦点。本文将详细介绍如何利用Cursor IDE结合阿里云百炼平台的Flux模型，构建一个本地化运行的高质量文生图服务。

通过本文，你将获得以下收益：

• 深入了解Flux系列模型的特性与应用场景
• 搭建完全本地化运行的高性能文生图服务
• 掌握Cursor IDE中MCP Tool的集成与使用技巧

Flux模型系列解析

Flux系列模型由Black Forest Labs团队（同时也是Stable Diffusion的核心开发团队）倾力打造，代表了当前文生图领域的前沿水平。该系列模型在图像质量、生成效率和提示词遵循度方面均有卓越表现。

数据来源：Hugging Face - FLUX.1-schnell ^[1]

模型家族成员

Flux系列模型根据不同使用场景提供三个版本：

Flux.1 Pro

• ? 旗舰级模型，提供顶尖图像生成性能
• ? 闭源模型，仅通过API服务访问
• ? 专为企业级应用和商业项目设计
• ✨ 最佳的图像质量和风格多样性表现

Flux.1 Dev

• ? 开发者友好的基础模型
• ? 从Pro版本蒸馏优化而来
• ? 特别强化了提示词精准遵循能力
• ?️ 在视觉细节表现方面接近专业级水准
• ?‍? 采用非商业许可证，适合社区开发和研究

Flux.1 Schnell

• ⚡ 速度优化版本，运行速度比Dev版本快约10倍
• ? 轻量级设计，最小化资源占用
• ? 适合边缘设备和本地部署场景
• ? 采用Apache 2.0许可证，支持个人和商业使用

与主流模型对比

Flux系列相比其他知名模型具有显著优势：

提示：阿里云百炼平台目前提供每个 Flux 模型1000次免费调用额度，非常适合开发者进行项目测试和学习实践。

实施流程

环境准备

项目依赖以下基础环境：

• 操作系统：MacOS/Linux/Windows（本文以MacOS为例）

• 开发工具：Cursor IDE 0.47.9+

• 编程语言：Python 3.8+（推荐3.13）

• 包管理工具：uv（推荐）或 pip

01 环境配置与依赖安装

我们选择使用现代化的uv作为Python包管理器，它提供更快的安装速度和更智能的依赖解析能力。

首先安装uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

然后初始化项目环境：

# 创建并进入项目目录
mkdir flux-image-service && cd flux-image-service

# 初始化Python项目
uv init
uv venv
source .venv/bin/activate

# 安装核心依赖
uv add "mcp[cli]" dashscope python-dotenv requests

02 实现MCP服务器

创建server.py文件，实现文生图核心功能：

from mcp.server.fastmcp import FastMCP
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import Path
import requests
from dashscope import ImageSynthesis
from dotenv import load_dotenv
import os
import json
from pathlib import PurePosixPath

# 加载环境变量
load_dotenv()

# 创建MCP服务器实例
mcp = FastMCP("flux-schnell-server")

# 配置输出目录
OUTPUT_DIR = Path("output")
OUTPUT_DIR.mkdir(parents=True, exist_ok=True)

# 获取当前工作目录的绝对路径
CURRENT_DIR = Path.cwd().resolve()
print(f"MCP服务器工作目录：{CURRENT_DIR}")


# 定义文生图工具
@mcp.tool()
defgenerate_image(prompt: str) -> dict:
    """Generate an image from text prompt using flux-schnell/flux-dev model

    Args:
        prompt (str): 图片生成提示词

    Returns:
        dict: 包含生成状态、图片路径等信息的字典
    """
    model = "flux-dev"# 也可选择"flux-schnell"用于更快速度
    api_key = os.getenv("DASH_API_KEY")
    ifnot api_key:
        error_msg = {
            "status": "error",
            "message": "DASH_API_KEY not found in config or environment variables",
        }
        print(f"错误：{json.dumps(error_msg, ensure_ascii=False)}")
        return error_msg

    try:
        print(f"开始生成图片，提示词：{prompt}")
        rsp = ImageSynthesis.call(
            model=model, prompt=prompt, size="1024*1024", api_key=api_key
        )
        print(f"API响应状态码：{rsp.status_code}")
        print(f"API响应内容：{rsp}")

        if rsp.status_code == HTTPStatus.OK:
            # 保存文件到output目录
            image_paths = []
            for result in rsp.output.results:
                file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
                # 使用相对路径存储
                relative_path = f"output/{file_name}"
                output_path = OUTPUT_DIR / file_name

                print(f"正在保存图片：{relative_path}")
                withopen(output_path, "wb+") as f:
                    f.write(requests.get(result.url).content)
                # 转换为绝对路径
                absolute_path = str((CURRENT_DIR / relative_path).resolve())
                image_paths.append(absolute_path)

            result = {
                "status": "success",
                "image_paths": image_paths,
            }
            print(f"图片生成成功：{json.dumps(result, ensure_ascii=False)}")
            return result
        else:
            error_msg = {
                "status": "error",
                "status_code": rsp.status_code,
                "code": rsp.code,
                "message": rsp.message,
            }
            print(f"生成失败：{json.dumps(error_msg, ensure_ascii=False)}")
            return error_msg
    except Exception as e:
        error_msg = {"status": "error", "message": f"发生异常：{str(e)}"}
        print(f"发生异常：{error_msg}")
        return error_msg


# 运行服务器
if __name__ == "__main__":
    mcp.run()

    # 调试用代码（正式使用时注释掉）
    # prompt = "一只可爱的橘猫在阳光下打盹"
    # result = generate_image(prompt)

03 API密钥配置

安全提示：API密钥属于敏感信息，切勿提交至代码仓库或公开分享。建议使用环境变量或本地配置文件管理。

1. 访问阿里云百炼平台 ^[2]并完成账号注册

2. 完成实名认证流程（个人或企业均可）

3. 在控制台右上角用户图标下找到API-KEY选项

4. 创建并保存新的API密钥

在项目根目录创建.env文件存储密钥：

DASH_API_KEY=your_api_key_here

免费额度说明：百炼平台提供每个Flux模型半年内1000次免费调用额度，且三种模型额度独立计算，足够个人开发和学习使用。

04 Cursor集成配置

在Cursor中配置MCP工具需要创建特定的配置文件。

重要：请务必使用绝对路径，避免路径解析错误导致服务无法启动。

创建.cursor/mcp.json文件：

{
  "mcpServers":{
    "flux-schnell-server":{
      "command":"/full/path/to/uv",
      "args":[
        "--directory",
        "/full/path/to/project",
        "run",
        "server.py"
      ]
    }
}
}

配置说明：

• 将/full/path/to/uv替换为你本地uv可执行文件的完整路径

• 将/full/path/to/project替换为存放server.py的项目目录绝对路径

配置成功后，Cursor界面中将显示绿色指示点，表示MCP服务已成功集成：

效果展示

以下是使用Flux模型生成的部分高质量示例图片：

更多精彩作品展示：

最后以 Flux 最拿手的网红照片生成为例：

提示词如下： 

上海人气甜品店的大理石桌前，一位22岁的中国女孩，黑色微烫长发呈现完美'C位刘海'造型，发尾做了挑染奶茶色渐变。皮肤呈现韩式'水光肌'效果，透明感十足，眼妆采用上扬式'狐狸眼'，睫毛根根分明且微卷。镜头采用45度仰角拍摄，背景虚化呈现奶油色'糖果风'滤镜效果，女孩左手拿着粉色珍珠奶茶，右手轻托腮，手腕上佩戴细版金属手链。穿着淡粉色毛衣搭配米色A字裙，妆容精致但呈现'伪素颜'效果。光线营造出instagram风格的暖黄色调，桌上放着半开的笔记本和一盘装饰精美的马卡龙，背景墙是网红必拍的植物墙，氛围感强烈。

如图所示，Flux模型生成的图像具有出色的细节表现、自然的色彩过渡和强烈的真实感，在艺术性和实用性之间达到了良好的平衡。