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

A professional image watermarking service built with FastMCP, supporting both text and image watermarks with intelligent color adaptation.

中文文档 | English

✨ Key Features

• 🖼️ Dual Watermark Modes: Support for both text and image watermarks

• 📂 Local File Processing: Professional local image file handling

• 🎨 Smart Adaptive Colors: Automatic color selection based on image brightness

• 📐 Tilted Watermark Effects: Customizable angle tilting (default 30° upward right)

• 🌍 Multi-language Support: Chinese, English, Japanese, Korean and more

• 🎯 High-density Coverage: Complete coverage of every corner with no gaps

• 💎 High Definition: BICUBIC resampling for smooth edges

• 📁 Smart Saving: Auto-save in the same directory as original image

• ⚡ Performance Optimized: Font caching, intelligent scaling, memory management

• 🛠️ Rich Format Support: Supports 7 common image formats

📖 Usage

MCP Client Configuration

Cherry Studio (Recommended)

1. Open Cherry Studio Settings

   • Go to Settings → MCP Servers

   • Click "Add Server"

2. Configure MCP Server

   

3. Save and Connect

   • Click "Save" to add the server

   • The server will automatically connect

   • You can now use the watermark tools in Cherry Studio

   

Cursor

1. Open Cursor Settings

   • Use shortcut Cmd+, (Mac) or Ctrl+, (Windows/Linux)

   • Or click Settings → Preferences

2. Configure MCP Server

   • Find "MCP Servers" configuration option

   • Add the following configuration:

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

3. Save and Restart

   • Save the configuration file

   • Restart Cursor for changes to take effect

   • You can now use the watermark tools in Cursor

📦 Preview

🚀 Installation

Using uv (Recommended)

# Install dependencies
uv pip install fastmcp pillow

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

Using pip

pip install fastmcp pillow

Start the MCP Server (Standalone)

python main.py

After the server starts, you will see output similar to:

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

Available MCP Tools

add_text_watermark - Text Watermark

Add intelligent text watermarks to images with multi-language support and adaptive colors.

Parameters:

• image_path (str): Local image file path

• watermark_text (str): Watermark text content

• angle (float, optional): Watermark tilt angle, default 30°

Usage Examples:

# 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 Watermark

Add image watermarks to photos, supporting logos, signatures, and other images as watermarks.

Parameters:

• image_path (str): Local image file path

• watermark_image_path (str): Watermark image file path

• angle (float, optional): Watermark tilt angle, default 30°

Usage Examples:

# 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)

🎨 Watermark Features

📝 Text Watermark Features

• Smart Color Adaptation

  • Bright images: Automatically use dark watermarks (RGB 20,20,20)

  • Dark images: Automatically use light/white watermarks (RGB 240,240,240)

  • Medium brightness: Intelligently select optimal contrast colors

• Multi-language Font Support

  • Auto-detect and load system's best Chinese fonts

  • Support for PingFang SC, Microsoft YaHei, SimHei, etc.

  • Perfect display of Chinese, Japanese, Korean, and English

• High-quality Rendering

  • Font caching for improved performance

  • BICUBIC resampling for smooth edges

  • Centered rendering with excellent rotation effects

🖼️ Image Watermark Features

• Smart Scaling: Auto-scale to appropriate size (default 15%)

• Opacity Control: Automatic opacity adjustment without affecting original image

• Aspect Ratio Preservation: Maintain watermark image aspect ratio

• High-quality Scaling: Use LANCZOS algorithm for clarity

🎯 Layout Algorithm

• Complete Coverage: Start from outside image boundaries for 100% coverage

• Staggered Arrangement: Odd-even row offset for more natural visual effect

• Dense Distribution: Optimized spacing algorithm, 40% higher density than traditional methods

• Edge Handling: Complete watermark coverage in all four corners

📁 File Output

Save Rules

• Save Location: Auto-save in the same directory as original image

• Naming Convention: Original filename + _watermark + extension

• Format Preservation: Maintain original image format and quality

• Optimized Saving: Enable compression optimization to reduce file size

Output Examples

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

🛠️ Supported Image Formats

🌍 Multi-language Font Support

Supported Languages

• Chinese: Simplified & Traditional Chinese

• Japanese: ひらがな、カタカナ、漢字

• Korean: 한글 (Hangul)

• English: Latin character set

• Others: Most Unicode characters

Font Priority

macOS System:

1. PingFang SC (Apple's default Chinese font)

2. STHeiti Light (Chinese typography)

3. Hiragino Sans GB (Winter Blue font)

4. Arial Unicode (Universal Unicode font)

Windows System:

1. Microsoft YaHei

2. SimSun

3. SimHei

Linux System:

1. DejaVu Sans

2. Liberation Sans

3. Noto Sans CJK

4. WenQuanYi Zen Hei

📂 Project Structure

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

🧪 Quick Testing

Test Text Watermark

# 1. Start server
python main.py

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

Test Image Watermark

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

⚙️ Technical Details

Core Algorithms

• Brightness Calculation: Grayscale conversion + pixel average algorithm

• Color Adaptation: Four-tier classification system based on brightness thresholds

• Position Calculation: Staggered grid + edge offset algorithm

• Rendering Optimization: BICUBIC/LANCZOS resampling technology

Performance Optimization

• Font Caching: Avoid repeated font file loading

• Smart Scaling: Brightness calculation using 50x50 small images for speed

• Memory Management: Timely release of temporary layers and cache

• Batch Processing: Support for efficient batch image processing

Quality Assurance

• Edge Smoothing: Use high-quality resampling algorithms

• Color Fidelity: Preserve original image color space and mode

• Transparency Handling: Proper RGBA channel processing

• Format Compatibility: Smart conversion between different image formats

🔧 Advanced Configuration

You can adjust parameters by modifying the WatermarkConfig class:

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
    }

Custom Parameter Suggestions

• Dense Watermarks: Lower spacing multipliers (0.8, 0.7)

• Sparse Watermarks: Higher spacing multipliers (1.5, 1.3)

• Large Fonts: Increase font size (48, 54)

• Small Fonts: Decrease font size (24, 30)

🎛️ Usage Tips

Text Watermark Tips

1. Copyright Info: Use "© 2024 Company Name" format

2. Multi-language: Mixed Chinese-English works better

3. Angle Selection: 30° most natural, 45° more prominent, 0° for documents

Image Watermark Tips

1. Logo Design: Use transparent background PNG format

2. Size Control: Logo shouldn't be too large, recommend within 15% of original

3. Color Matching: Choose logo colors with appropriate contrast to original image

💡 Best Practices

Batch Processing Recommendations

# 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)

Performance Optimization Suggestions

1. Use same font size in batches to leverage font caching

2. Avoid frequent angle changes to reduce computational overhead

3. Use small-sized image watermarks to improve processing speed

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

🤝 Contributing

Issues and Pull Requests are welcome!

Contributing Guidelines

1. Fork the project

2. Create a feature branch

3. Commit your changes

4. Submit a Pull Request

📞 Technical Support

For questions or suggestions:

1. Submit GitHub Issues

2. Check project documentation

3. Contact development team

🎉 Thank you for using Stamp it!