gpt-edit/SETUP_GUIDE.md

GPT-Edit MCP Server Setup Guide

🚀 Quick Setup

1. Install GPT-Edit

# Clone or navigate to the project
cd D:\Project\gpt-edit

# Install dependencies
pip install -r requirements.txt

2. Configure API Key

Create a .env file in the project directory:

# Required
OPENAI_API_KEY=sk-your-api-key-here

# Directory paths (optional)
INPUT_PATH=./input_images
GENERATED_IMAGES_PATH=./generated_images

3. Configure Claude Desktop

Add GPT-Edit to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gpt-edit": {
      "command": "python",
      "args": ["D:\\Project\\gpt-edit\\main.py"]"
    }
  }
}

4. Restart Claude Desktop

After saving the configuration, restart Claude Desktop completely.

⚙️ Configuration Options

Environment Variables

Create a .env file in the project root:

# Required
OPENAI_API_KEY=sk-your-api-key-here

# Directory Configuration (optional)
INPUT_PATH=./input_images                    # Source images directory
GENERATED_IMAGES_PATH=./generated_images     # Output directory

# File naming and processing (optional with defaults)
OUTPUT_FILENAME_PREFIX=gptimage1
MAX_IMAGE_SIZE_MB=4
DEFAULT_TIMEOUT=30
ENABLE_AUTO_OPTIMIZE=true
SAVE_ORIGINALS=true
SAVE_PARAMETERS=true
LOG_LEVEL=INFO

Environment Variable Reference

Variable	Description	Default	Example
OPENAI_API_KEY	Required - Your OpenAI API key	-	sk-xxxxx
INPUT_PATH	Directory for source images	./input_images	./my_images
GENERATED_IMAGES_PATH	Directory for output files	./generated_images	./results
OUTPUT_FILENAME_PREFIX	Prefix for output files	gptimage1	my_edit
MAX_IMAGE_SIZE_MB	Auto-optimize threshold	4	1-10
DEFAULT_TIMEOUT	API request timeout (seconds)	30	60
ENABLE_AUTO_OPTIMIZE	Auto WebP conversion	true	true/false
SAVE_ORIGINALS	Copy input images to output	true	true/false
SAVE_PARAMETERS	Save JSON parameters	true	true/false
LOG_LEVEL	Logging level	INFO	DEBUG, WARNING

📁 File Structure

After running, GPT-Edit creates this structure:

gpt-edit/
├── input_images/                  # Source images (INPUT_PATH)
│   ├── photo.jpg
│   ├── portrait.png
│   └── mask.png
├── generated_images/              # All output files (GENERATED_IMAGES_PATH)
│   ├── gptimage1_20250824_143022_000.png   # Original (copied from input)
│   ├── gptimage1_20250824_143022_001.png   # Edited output
│   └── gptimage1_20250824_143022_001.json  # Edit parameters
├── temp/                          # Temporary files (auto-cleaned)
└── gpt-edit.log                   # Debug log

🎯 Usage Examples in Claude

Method 1: File-based editing (Recommended)

I placed photo.jpg in the input_images folder. 
Can you edit it using edit_image_from_file to make it more vibrant?

Method 2: Direct upload editing

I have an image I'd like to edit. Can you make it more colorful and vibrant?
[Upload image to Claude]

Method 3: Mask-based editing

I have photo.jpg and mask.png in input_images/. 
Can you use edit_with_mask_from_file to replace only the background?

🔍 Troubleshooting

Common Issues and Solutions

"Server disconnected"

1. Check Python is installed: python --version
2. Verify dependencies: pip list | grep mcp
3. Check .env file exists with API key
4. Look at gpt-edit.log for errors

"API key not found"

1. Ensure .env file is in project root (same folder as main.py)
2. Check API key format: OPENAI_API_KEY=sk-xxxxx
3. No quotes needed around the key

"Method not found"

1. Update to latest code: git pull
2. Reinstall dependencies: pip install -r requirements.txt
3. Restart Claude Desktop completely

"Image too large"

• Enable auto-optimization: ENABLE_AUTO_OPTIMIZE=true
• Or increase limit: MAX_IMAGE_SIZE_MB=8

"Cannot find output images"

• Check generated_images/ folder
• Files named: gptimage1_{seed}_{date}_{time}_{number}.png
• Look for most recent by timestamp

Verify Installation

Test the setup:

python main.py

You should see:

Starting GPTEdit MCP Server
GPTEdit MCP Server is running...
Ready to process image editing requests

Press Ctrl+C to stop.

🛡️ Security Best Practices

1. API Key Management

   • Store API key only in .env file
   • Never commit .env to version control
   • Add .env to .gitignore

2. File Permissions

   • Ensure generated_images/ is writable
   • Keep sensitive files in project directory only

3. Logging

   • Use INFO level for normal operation
   • DEBUG only for troubleshooting
   • Rotate logs periodically

📚 Additional Resources

• OpenAI API Documentation
• MCP Protocol Specification
• Project README
• Technical Specifications

💡 Tips

1. Performance

   • Smaller images (512x512) process faster
   • Batch editing is more efficient than individual edits
   • WebP format reduces file sizes significantly

2. Quality

   • Use clear, specific prompts
   • Provide masks for precise edits
   • Save parameters for reproducibility

3. Organization

   • Files are grouped by session (same seed)
   • JSON parameters allow replay of edits
   • Timestamps help track edit history

🆘 Support

For issues:

1. Check gptedit.log for detailed errors
2. Verify OpenAI API key has credits
3. Ensure all paths are accessible
4. Create an issue on GitHub

---

Happy editing with GPT-Edit! 🎨