Stamp it - Apply a full-screen watermark to an image

🎯 Stamp it - 为图像添加全屏水印

基于 FastMCP 构建的专业图像水印服务，支持文本和图像水印，并可智能适配颜色。

中文文档 | English

✨ 主要功能

• 🖼️ 双水印模式：支持文本和图像水印
• 📂 本地文件处理：专业的本地图像文件处理
• 🎨 智能自适应颜色：根据图像亮度自动选择颜色
• 📐 倾斜水印效果：可自定义倾斜角度（默认向右上方倾斜 30°）
• 🌍 多语言支持：中文、英语、日语、韩语等
• 🎯 高密度覆盖：完整覆盖每个角落，不留空隙
• 💎 高清画质：使用 BICUBIC 重采样，使边缘平滑
• 📁 智能保存：自动保存在原图所在目录
• ⚡ 性能优化：字体缓存、智能缩放和内存管理
• 🛠️ 丰富的格式支持：支持 7 种常见图像格式

📖 使用方法

MCP 客户端配置

Cherry Studio（推荐）

1. 打开 Cherry Studio 设置

   • 前往 Settings → MCP Servers
   • 点击“Add Server”

2. 配置 MCP 服务

   

3. 保存并连接

   • 点击“Save”添加服务
   • 服务将自动连接
   • 现在可以在 Cherry Studio 中使用水印工具

   

Cursor

1. 打开 Cursor 设置

   • 使用快捷键 Cmd+,（Mac）或 Ctrl+,（Windows/Linux）
   • 或点击 Settings → Preferences

2. 配置 MCP 服务

   • 找到“MCP Servers”配置选项
   • 添加以下配置：

{
  "mcpServers": {
    "stampit": {
      "command": "uvx",
      "args": [
        "mcp-stampit"
      ]
    }
  }
}

3. 保存并重启
   • 保存配置文件
   • 重启 Cursor 以使更改生效
   • 现在可以在 Cursor 中使用水印工具

📦 预览

🚀 安装

使用 uv（推荐）

# Install dependencies
uv pip install fastmcp pillow

# Or install using project configuration
uv pip install -e .

使用 pip

pip install fastmcp pillow

启动 MCP 服务（独立运行）

python main.py

服务启动后，你会看到类似以下的输出：

╭─ FastMCP 2.0 ──────────────────────────────────────────────────────────────────╮
│   🖥️  Server name:     Stamp it - Apply a full-screen watermark to an image    │
│   📦 Transport:       STDIO                                                    │
╰────────────────────────────────────────────────────────────────────────────────╯

可用的 MCP 工具

add_text_watermark - 文本水印

为图像添加智能文本水印，支持多语言和自适应颜色。

参数：

• image_path（str）：本地图像文件路径
• watermark_text（str）：水印文本内容
• angle（float，可选）：水印倾斜角度，默认 30°

使用示例：

# Basic text watermark
add_text_watermark("/Users/photos/vacation.jpg", "My Copyright")

# Custom angle
add_text_watermark("./document.png", "Confidential", angle=45)

# Multi-language watermark
add_text_watermark("photo.jpg", "Copyright © 2024 All Rights Reserved")

add_image_watermark - 图像水印

为照片添加图像水印，支持将徽标、签名和其他图像用作水印。

参数：

• image_path（str）：本地图像文件路径
• watermark_image_path（str）：水印图像文件路径
• angle（float，可选）：水印倾斜角度，默认 30°

使用示例：

# Add logo watermark
add_image_watermark("/Users/photos/product.jpg", "/Users/logos/company_logo.png")

# Custom angle logo watermark
add_image_watermark("photo.jpg", "signature.png", angle=0)

# Brand watermark
add_image_watermark("marketing_image.jpg", "brand_watermark.png", angle=15)

🎨 水印功能

📝 文本水印功能

• 智能颜色适配

  • 明亮图像：自动使用深色水印（RGB 20,20,20）
  • 暗色图像：自动使用浅色／白色水印（RGB 240,240,240）
  • 中等亮度：智能选择对比度最佳的颜色

• 多语言字体支持

  • 自动检测并加载系统中最佳的中文字体
  • 支持 PingFang SC、Microsoft YaHei、SimHei 等
  • 完美呈现中文、日语、韩语和英语

• 高质量渲染

  • 使用字体缓存提升性能
  • 使用 BICUBIC 重采样，使边缘平滑
  • 居中渲染，旋转效果出色

🖼️ 图像水印功能

• 智能缩放：自动缩放至合适尺寸（默认 15%）
• 不透明度控制：自动调整不透明度，不影响原图
• 保持宽高比：保持水印图像的宽高比
• 高质量缩放：使用 LANCZOS 算法，确保清晰度

🎯 布局算法

• 完整覆盖：从图像边界之外开始，确保 100% 覆盖
• 交错排列：奇偶行偏移，呈现更自然的视觉效果
• 密集分布：优化间距算法，密度比传统方法高 40%
• 边缘处理：确保四个角都完整覆盖水印

📁 文件输出

保存规则

• 保存位置：自动保存在原图所在目录
• 命名规则：原文件名 + _watermark + 扩展名
• 格式保持：保持原图格式和质量
• 优化保存：启用压缩优化以减小文件体积

输出示例

Input:  /Users/photos/vacation.jpg
Output: /Users/photos/vacation_watermark.jpg

Input:  ./designs/logo.png
Output: ./designs/logo_watermark.png

Input:  document.pdf.png
Output: document.pdf_watermark.png

🛠️ 支持的图像格式

格式	扩展名	读取	保存	透明度	已优化
JPEG	.jpg, .jpeg	✅	✅	❌	✅
PNG	.png	✅	✅	✅	✅
GIF	.gif	✅	✅	✅	✅
BMP	.bmp	✅	✅	❌	✅
TIFF	.tiff, .tif	✅	✅	✅	✅
WebP	.webp	✅	✅	✅	✅

🌍 多语言字体支持

支持的语言

• 中文：简体中文和繁体中文
• 日语：ひらがな、カタカナ、漢字
• 韩语：한글（Hangul）
• 英语：拉丁字符集
• 其他：大多数 Unicode 字符

字体优先级

macOS 系统：

1. PingFang SC（Apple 的默认中文字体）
2. STHeiti Light（中文字体）
3. Hiragino Sans GB（冬青黑体）
4. Arial Unicode（通用 Unicode 字体）

Windows 系统：

1. Microsoft YaHei
2. SimSun
3. SimHei

Linux 系统：

1. DejaVu Sans
2. Liberation Sans
3. Noto Sans CJK
4. WenQuanYi Zen Hei

📂 项目结构

stampit/
├── main.py                   # Main program and MCP server
├── pyproject.toml            # Project configuration
├── README.md                 # English project documentation
├── README_CN.md              # Chinese project documentation
├── uv.lock                   # Dependency lock file
└── LICENSE                   # License file

🧪 快速测试

测试文字水印

# 1. Start server
python main.py

# 2. Call in MCP client
add_text_watermark("path/to/your/image.jpg", "Test Watermark")

测试图像水印

# 1. Prepare a logo image
# 2. Call in MCP client
add_image_watermark("path/to/your/photo.jpg", "path/to/logo.png")

⚙️ 技术细节

核心算法

• 亮度计算：灰度转换 + 像素平均算法
• 颜色自适应：基于亮度阈值的四级分类系统
• 位置计算：交错网格 + 边缘偏移算法
• 渲染优化：BICUBIC/LANCZOS 重采样技术

性能优化

• 字体缓存：避免重复加载字体文件
• 智能缩放：使用 50x50 小图像计算亮度，以提升速度
• 内存管理：及时释放临时图层和缓存
• 批量处理：支持高效批量处理图像

质量保障

• 边缘平滑：使用高质量重采样算法
• 颜色保真：保留原图的颜色空间和模式
• 透明度处理：正确处理 RGBA 通道
• 格式兼容：在不同图像格式之间进行智能转换

🔧 高级配置

你可以通过修改 WatermarkConfig 类来调整参数：

class WatermarkConfig:
    DEFAULT_FONT_SIZE = 36          # Default font size
    DEFAULT_ANGLE = 30              # Default tilt angle
    SPACING_X_FACTOR = 1.1          # Horizontal spacing multiplier
    SPACING_Y_FACTOR = 0.9          # Vertical spacing multiplier
    BRIGHTNESS_THRESHOLDS = {       # Brightness thresholds
        'very_bright': 180,
        'medium': 120,
        'dark': 60
    }

自定义参数建议

• 密集水印：调低间距倍数（0.8、0.7）
• 稀疏水印：调高间距倍数（1.5、1.3）
• 大号字体：增大字号（48、54）
• 小号字体：减小字号（24、30）

🎛️ 使用技巧

文字水印技巧

1. 版权信息：使用“© 2024 Company Name”格式
2. 多语言：中英混排效果更佳
3. 角度选择：30° 最自然，45° 更醒目，0° 适用于文档

图像水印技巧

1. Logo 设计：使用透明背景的 PNG 格式
2. 尺寸控制：Logo 不宜过大，建议不超过原图的 15%
3. 颜色搭配：选择与原图有适当对比度的 Logo 颜色

💡 最佳实践

批量处理建议

# Recommended batch processing method
images = ["photo1.jpg", "photo2.jpg", "photo3.jpg"]
watermark_text = "© 2024 My Company"

for image_path in images:
    result = add_text_watermark(image_path, watermark_text)
    print(result)

性能优化建议

1. 批量使用相同字号，以利用字体缓存
2. 避免频繁更改角度，以减少计算开销
3. 使用小尺寸图片水印，以提升处理速度

📄 许可证

本项目采用 Apache 2.0 许可证授权，详情请参阅 LICENSE 文件。

🤝 贡献

欢迎提交问题和拉取请求！

贡献指南

1. Fork 本项目
2. 创建功能分支
3. 提交更改
4. 提交拉取请求

📞 技术支持

如有问题或建议：

1. 提交 GitHub Issues
2. 查阅项目文档
3. 联系开发团队

---

🎉 感谢使用 Stamp it！