使用说明

Fal-AI - ImageKit MCP 服务器

一个使用MCP（模型上下文协议）的服务器，用于生成图像 fal.ai的Imagen4 Ultra模型并自动将它们上传到 ImageKit（图像工具/图像处理工具）用于永久托管。

注该项目将谷歌的Imagen4 Ultra（最高质量的图像生成技术）与ImageKit相结合，以提供可靠的云托管服务。

特点/功能

🎨 表示“艺术”或“绘画”的意思。 高质量生成通过fal.ai使用谷歌的Imagen4 Ultra模型
📤 翻译成中文是：（一个放东西的篮子或盒子，通常指放在外面的） 自动上传直接上传到ImageKit进行永久托管
🖼️（图片） 固定为4:3宽高比稳定的输出，适用于大多数使用场景
⚙️（齿轮符号，常用于表示机械装置、设置或调整等含义） 可配置分辨率选择1K或2K画质
🚫（这个符号本身没有直接对应的中文翻译，它通常表示“禁止”或“不允许”的意思，在中文中可以表达为“禁止”或根据上下文用相应的词汇来传达其含义。） **负面提示（或：否定提示）**更好地控制图像中应排除的内容
🌱（种子/嫩芽） 种子追踪相似图像生成的可重复性
🔒（锁形符号，通常表示安全、保密或锁定状态）安全通过MCP配置管理的API密钥
⚡（闪电符号，常用于表示速度、能量或惊喜等含义） 快速集成与Cursor和Claude Desktop无缝协作

先决条件

在使用此MCP服务器之前，您需要：

1. Node.js

版本18或更高版本
请与以下人员核实： node --version

2. fal.ai API密钥

在……注册 fal.ai（该名称本身在中文中无直接对应翻译，但可解释为“人工智能学习平台”或保持原样作为专有名词使用）
导航至仪表盘/密钥
复制您的API密钥

3. ImageKit 账户

在……注册 imagekit.io
去你的（这里根据语境，可以理解为“去你的地方”或“去你的位置”，但直接翻译可能略显生硬，具体含义需结合上下文）仪表盘
复制你的：
- 公钥
- 私钥

安装

克隆或下载此仓库

安装依赖项：

cd /path/to/image-generator-mcp
npm install

构建项目：
```
npm run build
```

编译后的服务器将位于 dist/ 目录。

配置

对于Cursor

找到您的MCP配置文件:
- MacOS（中文可译为“麦奥斯”，但通常直接使用英文原名）: ~/.cursor/mcp.json
- Linux（发音为“林克斯”）： ~/.config/cursor/mcp.json
- Windows： %APPDATA%\Cursor\mcp.json
添加服务器配置:

{
  "mcpServers": {
    "fal-imagekit": {
      "command": "/usr/local/bin/node",
      "args": [
        "/absolute/path/to/image-generator-mcp/dist/index.js"
      ],
      "env": {
        "FAL_KEY": "your_fal_api_key_here",
        "IMAGEKIT_PUBLIC_KEY": "your_imagekit_public_key_here",
        "IMAGEKIT_PRIVATE_KEY": "your_imagekit_private_key_here"
      }
    }
  }
}

重要的：
- 替换 /absolute/path/to/image-generator-mcp 使用您的实际安装路径
- 将所有占位符API密钥替换为您的实际凭据
- 如果 /usr/local/bin/node 不起作用，请用以下方式找到你的 Node.js 路径： which node (见故障排除）
重启光标

对于Claude Desktop

找到您的配置文件：
- MacOS（发音为“Mac OS”）: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows： %APPDATA%\Claude\claude_desktop_config.json
添加相同的配置 如上文所示（针对Cursor）
重启Claude桌面版

环境变量说明

MCP服务器从Cursor/Claude通过环境变量传递给它的API密钥中读取数据 env 在你的配置中设置部分。你可以不要需要创建一个单独的 .env 文件——所有配置均通过MCP配置文件进行设置。

这种方法：

✅ 在您的IDE配置中安全保存凭据
✅ 简化设置（一个配置位置）
✅ 与Cursor和Claude Desktop无缝协作
✅ 无需额外的环境变量管理

快速入门

配置完成后，尝试这个简单的测试：

Generate an image of a cute cat wearing sunglasses

你应该会收到这样的回复：

{
  "success": true,
  "imagekitUrl": "https://ik.imagekit.io/your-id/generated-1234567890.png",
  "falImageUrl": "https://v3.fal.media/files/...",
  "seed": 42,
  "message": "Image generated and uploaded successfully!"
}

**imagekitUrl**使用这个URL - 它是永久的，并托管在ImageKit上
**falImageUrl**来自fal.ai的原始URL（临时，仅供参考）
**seed**保存此文件以便日后重新生成类似图像

使用示例

基本示例

示例1：简单风景

Generate an image of a peaceful mountain landscape with a lake in the foreground

示例2：角色肖像

Generate an image of a friendly robot character with big eyes and a smile

示例3：室内场景

Generate an image of a modern minimalist living room with large windows and natural light

高级示例

带有负面提示

Generate an image with these specifications:
- Prompt: A detailed steampunk airship floating above Victorian-era city
- Negative prompt: blurry, low quality, distorted, ugly, cropped

高分辨率

Generate a high-resolution image:
- Prompt: A majestic dragon perched on a mountain peak at dawn
- Resolution: 2K

美食摄影

Generate an image:
- Prompt: A gourmet burger with melted cheese, fresh vegetables, perfectly styled on a wooden board with dramatic lighting
- Negative prompt: artificial, plastic, unappetizing, blurry
- Resolution: 2K

抽象艺术

Generate an image of flowing abstract shapes in vibrant colors, reminiscent of oil painting with bold brushstrokes

提升提示质量的小贴士

1. 要具体

❌（表示错误或否定的符号，无直接对应中文含义，可理解为“错误”或“不”） 贫穷的；可怜的“一辆车”
✅ 好的“夕阳下的山路上，一辆流线型的红色跑车”

2. 包含样式引用

Generate an image of a fantasy castle in the style of watercolor painting with soft colors and dreamy atmosphere

3. 使用描述性形容词

Generate an image of a cozy coffee shop interior with warm lighting, rustic wooden furniture, hanging plants, and vintage decor

4. 指定照明

Generate an image of a forest path with dappled sunlight filtering through the trees, creating dramatic light and shadow

5. 有效利用否定提示词

常见的负面提示词：

质量问题： blurry, low quality, distorted, pixelated, noise
组合问题: cropped, cut off, out of frame, bad framing
风格问题: ugly, deformed, disfigured, poor details
文本问题： text, watermark, signature, letters

实际应用场景

博客文章标题

Generate an image of an open book with a warm coffee cup, soft morning light, cozy reading nook atmosphere, perfect for blog header

产品模型/产品模拟图

Generate an image of a sleek smartphone displaying a colorful app interface, placed on a minimalist desk with soft shadows

社交媒体内容

Generate an image for Instagram post:
- Prompt: Flat lay of healthy breakfast bowl with fruits, granola, and yogurt, bright natural lighting, food photography style
- Resolution: 2K
- Negative prompt: unappetizing, artificial, oversaturated

演示背景

Generate an image of abstract geometric patterns in blue and purple gradients, modern and professional, suitable for presentation background

专业技巧

宽高比所有图片均为4:3格式（非常适合风景、产品、主图、博客标题）
分辨率选择：
- 使用 1K 用于：快速预览、社交媒体、网页缩略图
- 使用 2K 用于：英雄图片、印刷材料、高质量展示
迭代策略:
- 从1K开始测试你的提示
- 根据结果进行优化
- 生成2K分辨率的最终版本
保存你的种子如果你喜欢某个图像，请记下其种子，以便日后生成类似的图像

工具规格

工具名称

generate_and_upload_image

输入参数

参数	类型	必需	描述
中文翻译	中文	英文	其他语言
字符串	是	您想要生成的图像的文本描述	`negative_prompt`
字符串	否	描述在生成的图像中应避免的内容	`resolution`

| 字符串 | 否 | 图像分辨率：“1K”或“2K”（默认：“1K”） |

{
  "prompt": "string (required)",
  "negative_prompt": "string (optional)",
  "resolution": "1K | 2K (optional, default: 1K)"
}

输入模式（或输入架构）

{
  "success": true,
  "imagekitUrl": "https://ik.imagekit.io/...",
  "falImageUrl": "https://v3.fal.media/...",
  "seed": 42,
  "message": "Image generated and uploaded successfully!"
}

输出模式（或输出架构）

**imagekitUrl**响应字段
**falImageUrl**在ImageKit上托管您的图片的永久URL（生产环境中使用此URL）
**seed**来自fal.ai的原始URL（临时，仅供参考）

用于生成的种子（有助于生成相似图像）

技术细节

User Prompt
    ↓
MCP Tool Call
    ↓
fal.ai API (Generate Image with Imagen4 Ultra)
    ↓
Download Image Buffer
    ↓
ImageKit API (Upload to Cloud Storage)
    ↓
Return URLs + Seed

建筑学

图像生成流程生成
服务器使用您的提示调用fal.ai的Imagen4 Ultra API下载
生成的图像已从fal.ai的临时存储中下载上传
图片已上传至ImageKit进行永久托管返回

两个URL都被返回（生产环境使用ImageKit，参考环境使用fal.ai）

宽高比 所有图像均通过……生成4:3 横纵比

这提供了一个经典、均衡的构图，适用于：
横屏方向
产品摄影
主角图像（或：英雄图像）
博客标题

营销材料

分辨率选项1K
**生成速度更快，文件大小更小（约10-20秒）**2K

更高的质量，更大的文件大小（约20-40秒）

依赖项@modelcontextprotocol/sdk 翻译为中文是：“@模型上下文协议/开发工具包”。不过，这里的“@”符号在中文语境下通常不直接用于描述软件包或SDK的名称，它更多地出现在社交媒体或特定平台的标签中。在正式的中文文档或描述中，我们可能会省略“@”符号，直接翻译为“模型上下文协议开发工具包”或根据具体上下文进行更贴切的表述。但在这里，为了保持原意，我给出了包含“@”符号的翻译
MCP服务器框架node-fetch
API调用的HTTP请求表单数据（或：multipart/form-data 格式数据）
用于ImageKit上传的多部分表单数据TypeScript

全面的类型安全性

image-generator-mcp/
├── src/
│   └── index.ts              # Main MCP server implementation
├── dist/                     # Compiled JavaScript
│   ├── index.js             # Executable MCP server
│   ├── index.d.ts           # TypeScript definitions
│   └── *.map                # Source maps
├── package.json             # Dependencies and scripts
├── tsconfig.json            # TypeScript configuration
├── .gitignore               # Git ignore rules
├── README.md                # This file
└── mcp-config-example.json  # Configuration example

项目结构

故障排除

“FAL_KEY 环境变量未设置” FAL_KEY ✅ 确认你已添加 env 到……的
在您的MCP配置中的部分
✅ 确保密钥中没有拼写错误或多余的空格

✅ 更新配置后重启您的集成开发环境（IDE）

"ImageKit 凭证未设置" IMAGEKIT_PUBLIC_KEY ✅ 验证两者 IMAGEKIT_PRIVATE_KEY 和
存在
✅ 检查密钥中是否存在任何复制粘贴错误

✅ 确保没有多余空格

服务器未在 Cursor/Claude 中显示 args ✅ 确认路径在 dist/index.js
是正确的，并且指出dist/ ✅ 验证文件存在且构建成功（
文件夹存在) node_modules/ ✅ 检查确认
存在（已安装依赖项）
✅ 完全重启您的集成开发环境（IDE）

✅ 检查MCP日志中的错误

**“spawn node ENOENT”或“Command not found”错误（macOS/Linux）**症状 spawn node ENOENT Cursor无法检测到MCP工具，日志显示

或类似错误原因 node 光标无法找到

其PATH环境中的命令解决方案 node 使用Node.js的完整路径，而不是仅仅使用

{
  "mcpServers": {
    "fal-imagekit": {
      "command": "/usr/local/bin/node",  // Full path instead of "node"
      "args": [
        "/absolute/path/to/image-generator-mcp/dist/index.js"
      ],
      "env": {
        "FAL_KEY": "your_fal_api_key_here",
        "IMAGEKIT_PUBLIC_KEY": "your_imagekit_public_key_here",
        "IMAGEKIT_PRIVATE_KEY": "your_imagekit_private_key_here"
      }
    }
  }
}

**在您的MCP配置中：**查找您的 Node.js 路径

which node

：

/usr/local/bin/node 常见路径：
/opt/homebrew/bin/node （在Intel Mac上的Homebrew）
/usr/bin/node （在苹果硅芯片上的Homebrew）
~/.nvm/versions/node/vX.X.X/bin/node （系统安装）

（如果使用nvm） 更新配置后， 完全重启 Cursor

(同时按Cmd+Q然后重新打开)

“生成图像失败”✅ 确保您的fal.ai账户有足够的信用额度（在这里查看
）
✅ 验证您的fal.ai API密钥是否有效
✅ 检查您的网络连接

✅ 确认fal.ai服务正在运行

“无法上传到ImageKit”
✅ 确认您的ImageKit凭据正确无误
✅ 检查您的ImageKit账户是否处于活跃状态✅ 确保您没有超出ImageKit的存储或带宽限制（在这里查看

)

“命令失败”或“服务器错误” node --version ✅ 确保已安装 Node.js：
（需要版本18+） node_modules/ ✅ 验证依赖项是否已安装：检查是否
存在 npm run build
✅ 尝试重新构建：

✅ 在IDE的开发者控制台中检查MCP服务器日志

查看日志

**MCP 服务器将日志记录到标准错误输出。检查：**光标
**开发者工具控制台（帮助 → 切换开发者工具）**Claude Desktop（可译为“Claude桌面版”或保持原样，根据上下文判断是否需要具体翻译）

应用程序日志

# Using MCP Inspector (recommended)
npx @modelcontextprotocol/inspector node dist/index.js

# Or run directly
node dist/index.js

直接测试服务器

安全 **⚠️（警告符号，无具体文字含义，表示提醒或警告）**重要的

此服务器处理敏感的API密钥。请遵循以下安全最佳实践：

最佳实践 ✅ 确保您的MCP配置文件安全
并且永远不要将其提交到版本控制系统中 ✅ 安全存储API密钥
- 它们只存在于你本地的IDE配置中 ✅ 定期轮换您的API密钥
为了增强安全性 ✅ 监控使用情况在两者上 fal.ai 控制台/仪表板和
ImageKit 控制台 ✅ 设定使用限制

在两个平台上都进行（操作）以防止意外收费

它是如何工作的
API密钥通过您的MCP配置中的环境变量传递（而非硬编码）
私钥永远不会暴露在客户端代码中
ImageKit私钥仅用于服务器端的身份验证
所有请求均使用HTTPS加密

服务器在您的机器上本地运行，使用您的凭据

API 配额与限制

fal.ai（注：这个域名或项目名称直接翻译并无具体含义，通常保留原样或根据上下文意译为相关概念，如“法尔人工智能平台”等，但在此直接给出音译加原样保留的说明）请在以下网址查看您的积分：
https://fal.ai/dashboard（可翻译为）：https://fal.ai/仪表盘
每一代都会消耗信用额度
2K图像的价格高于1K图像

根据需要购买额外的信用额度

**ImageKit（意为“图像工具包”或“图像库”）**免费层/免费套餐
20GB 存储空间，每月20GB带宽检查限制条件于：
https://imagekit.io/仪表盘（或“控制面板”）

如需提高限额，请升级计划

定制化 src/index.ts想修改服务器吗？编辑

：

// Around line 56 in src/index.ts
const { imageUrl, seed } = await generateImageWithFal(
  prompt,
  "16:9",  // Change from "4:3" to desired ratio
  resolution,
  negativePrompt
);

更改宽高比 1:1可用的宽高比： 16:9， 9:16， 3:4， 4:3

，

添加更多工具 ListToolsRequestSchema 在（此处）添加新工具 CallToolRequestSchema处理并实现它们于

。

修改分辨率选项

更新输入模式，以在未来fal.ai支持的情况下添加“4K”或其他选项。

# Rebuild the project
npm run build

# Restart your IDE to pick up changes

定制后

发展

npm run dev

在开发模式下运行

npm run build

建筑

npm run build项目脚本
npm run dev将TypeScript编译为JavaScript
npm start使用 tsx 在开发模式下运行

运行编译后的服务器

API 参考MCP协议：
https://cursor.com/docs/context/mcp 翻译为中文是：“https://cursor.com 的文档/上下文/多上下文处理（MCP）”。不过，这里的“MCP”具体含义可能需要根据 Cursor.com 的实际文档内容来确定，因为“MCP”在不同领域可能有不同的解释。在没有具体上下文的情况下，我将其翻译为“多上下文处理（MCP）”，这是一个较为通用的解释fal.ai Imagen4 Ultra（可译为：“fal.ai 图像4 超级版”或根据具体语境调整为更贴切的表述）：
https://fal.ai/models/fal-ai/imagen4/preview/ultra 翻译为中文是：“https://fal.ai/models/fal-ai/imagen4/预览/超高清（或‘极致’）”。不过，这里的“ultra”在具体上下文中可能有特定的含义，比如表示某种超高清、极致性能或高级版本等，因此翻译时可能需要根据具体情境稍作调整。但基于通用理解，上述翻译是一个较为贴切的表述ImageKit上传API ：
https://docs.imagekit.io/api-reference/upload-file-api/服务器端文件上传提示工程指南：

https://fal.ai/models/fal-ai/imagen4/preview/ultra 翻译为中文是：“https://fal.ai/models/fal-ai/imagen4/预览/超高清” 或者更自然的表述可能是：“https://fal.ai/models/fal-ai/imagen4/预览版/极致清晰”。不过，具体翻译可能会根据网站或平台的官方中文表述有所调整

集成示例

<img 
  src="https://ik.imagekit.io/your-id/generated-123.png"
  alt="Generated landscape"
  width="800"
  height="600"
/>

在HTML中

<img
  src={result.imagekitUrl}
  alt="AI generated image"
  className="hero-image"
/>

在React中

![AI Generated Image](https://ik.imagekit.io/your-id/generated-123.png)

在Markdown中

许可证

麻省理工学院（MIT）

支持

**对于以下相关问题：**这台MCP服务器
在这个仓库中打开一个议题fal.ai API 联系
fal.ai 支持ImageKit（图像工具包）联系
ImageKit 支持MCP协议检查

MCP文档 准备开始生成了吗？遵循快速入门

**上面的指南！ 🎨**状态
✅ 已完成并随时可用版本
1.0.0最后更新时间