@tscodex/mcp-images
MCP (Model Context Protocol) server for comprehensive image processing, stock image search, and AI image generation. Built with TypeScript and Sharp for high-performance image manipulation.
Built on @tscodex/mcp-sdk - This project uses the official TSCodex MCP SDK for server infrastructure, authentication, configuration management, and protocol handling.
🚀 Quick Links
Desktop application for managing MCP servers | VS Code/Cursor extension bridge
🎯 What is This?
This is an MCP server built on the @tscodex/mcp-sdk that provides powerful image processing capabilities. It can work in two ways:
- Standalone Mode: Run directly via
npxornpm, passing environment variables and configuration - Managed Mode: Use with MCP Manager for workspace isolation, visual configuration, and seamless integration with Cursor
Architecture Overview
┌─────────────────────────────────────────────────────────────┐
│ Cursor (IDE Editor) │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ MCP Manager Bridge Extension │ │
│ │ - Auto-registers workspace │ │
│ │ - Syncs with MCP Manager │ │
│ │ - Updates Cursor mcp.json │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ HTTP API + WebSocket │
│ │ │
└─────────────────────────┼────────────────────────────────────┘
│
┌─────────────────────────┼────────────────────────────────────┐
│ MCP Manager (Desktop App) │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ - Process Management │ │
│ │ - Workspace Isolation (Proxy) │ │
│ │ - Visual Configuration UI │ │
│ │ - Secrets Management (3-level override) │ │
│ │ - Permissions System │ │
│ │ - AI Agent Proxy │ │
│ │ - MCP Tools (Dynamic Server) │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────┴────────────────┐ │
│ │ │ │
│ ┌──────▼──────┐ ┌──────▼──────┐ │
│ │ MCP Tools │ │ MCP Servers │ │
│ │ (Dynamic) │ │ (e.g. this) │ │
│ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │
└─────────┼─────────────────────────────────┼──────────────────┘
│ │
└────────────┬────────────────────┘
│
┌────────────▼────────────┐
│ @tscodex/mcp-sdk │
│ (Core SDK) │
└─────────────────────────┘
How It Works
The Problem: Real projects require each Cursor workspace to work with its own workspace context. For example, this image server needs the root path of the current project to create and work with images. But you can't run a separate server instance for each project.
The Solution: MCP Manager allows you to:
- Run one server instance (e.g.,
@tscodex/mcp-images) - Create multiple workspace proxies that forward requests with workspace context
- The SDK receives headers from the current workspace and allows one server to work with different workspaces
The Bridge: MCP Manager Bridge automatically:
- Registers the workspace in MCP Manager by project path
- Syncs Cursor with the manager
- Registers proxy MCP servers in local
mcp.json - Provides perfect encapsulation and connection between workspaces
🎨 Features
- 🖼️ Image Processing: Resize, crop, optimize, convert formats, apply filters, rotate, watermark
- 🔍 Stock Image Search: Search and download images from Pexels and Pixabay
- 🤖 AI Image Generation: Generate images using OpenAI DALL-E
- 🎨 Color Extraction: Extract dominant colors and generate color palettes
- 📦 Multiple Formats: Support for WebP, JPEG, PNG, AVIF
- ⚡ High Performance: Powered by Sharp for fast image processing
📦 Installation
Option 1: Standalone (via npx)
npx @tscodex/mcp-images@latest
Option 2: Global Installation
npm install -g @tscodex/mcp-images
Option 3: Managed Mode (Recommended)
Use with MCP Manager for the best experience:
- Install MCP Manager: Download from GitHub Releases
- Install Bridge Extension: MCP Manager Bridge from VS Code Marketplace
- Add Server: In MCP Manager, add
@tscodex/mcp-imagesas a new server - Configure: Use the visual UI to configure the server (JSON Schema-based)
- Enable: Enable the server for your workspace in Cursor
Benefits of Managed Mode:
- ✅ Visual Configuration: No need to edit JSON files manually
- ✅ Workspace Isolation: Each project gets its own workspace proxy
- ✅ Secure Secrets: 3-level secret override (Global → Workspace → Server)
- ✅ Permissions Control: Granular control over what each server can access
- ✅ AI Agent Integration: Use AI agents without exposing API keys to servers
- ✅ Token Statistics: Track AI usage transparently
- ✅ Auto-sync: Bridge automatically syncs with Cursor
🚀 Quick Start
Standalone Mode
# Start server with default settings
npx @tscodex/mcp-images@latest
# Server will start on port 3848 by default (host: 0.0.0.0)
# MCP endpoint: http://localhost:3848/mcp
# With custom host and port
npx @tscodex/mcp-images@latest --host 127.0.0.1 --port 3000
# With project root (REQUIRED for standalone mode)
npx @tscodex/mcp-images@latest --host 127.0.0.1 --port 4040 --root /path/to/project
# Get server metadata (for MCP Manager integration)
npx @tscodex/mcp-images@latest --meta
Managed Mode
- Start MCP Manager desktop application
- Open Cursor with your project
- Bridge Extension automatically:
- Registers your workspace
- Connects to MCP Manager
- Syncs enabled servers to Cursor's
mcp.json
- Enable Server: Click the play icon on
@tscodex/mcp-imagesin the Bridge panel - Configure: Use MCP Manager UI to configure the server (if needed)
⚙️ Configuration
Configuration File
Create .mcp-images.json in your project root:
{
"root": ".",
"defaultProvider": "pexels",
"defaultFormat": "webp",
"defaultMaxWidth": 1920,
"defaultQuality": 80,
"saveMetadata": true,
"embedExif": false
}
Configuration Options:
root(string, optional): Project root directory- Use
"."to useMCP_PROJECT_ROOTenvironment variable (managed mode) - Use absolute path for standalone mode
- Use
defaultProvider("pexels"|"pixabay"|"openai"|"auto", default:"auto"): Default image providerdefaultFormat("webp"|"jpeg"|"png"|"avif", default:"webp"): Default image formatdefaultMaxWidth(number, default:1920): Default maximum width (1-10000)defaultQuality(number, default:80): Default quality (1-100)saveMetadata(boolean, default:true): Save JSON metadata alongside imagesembedExif(boolean, default:false): Embed metadata in EXIF data
Secrets Management
⚠️ Security Note: API keys are stored as secrets (environment variables with SECRET_ prefix) instead of in configuration files.
In Standalone Mode:
export SECRET_PEXELS_API_KEY=your_pexels_api_key
export SECRET_PIXABAY_API_KEY=your_pixabay_api_key
export SECRET_OPENAI_API_KEY=your_openai_api_key
In Managed Mode: MCP Manager provides a 3-level secret override system:
- Global: Secrets available to all servers
- Workspace: Secrets specific to a workspace
- Server: Secrets specific to a server instance
This allows fine-grained control over what secrets each server can access.
Get API Keys:
- Pexels: https://www.pexels.com/api/
- Pixabay: https://pixabay.com/api/docs/
- OpenAI: https://platform.openai.com/api-keys
🔒 Security & Permissions
Security Features
MCP Manager provides enterprise-grade security:
- OS Keychain Storage: Secrets are stored in the operating system's secure keychain (Windows Credential Manager, macOS Keychain, Linux Secret Service)
- No Key Exposure: API keys are never passed directly to MCP servers. Servers that need AI access use the AI Agent proxy mechanism
- Process Isolation: Each server runs in its own process with isolated environment
- Permission System: Granular control over what each server can access
Permissions System
MCP Manager's permission system allows you to configure:
- Environment Variables: Which environment variables are available to the server
- Secrets Access: Which secrets the server can access
- AI Agent Access: Whether the server can use the AI Agent proxy
- File System Access: Workspace root access (always scoped to project)
Example Permission Configuration:
{
"envVars": ["NODE_ENV", "DEBUG"],
"secrets": ["SECRET_PEXELS_API_KEY", "SECRET_PIXABAY_API_KEY"],
"aiAgent": {
"enabled": true,
"allowedModels": ["gpt-4", "gpt-3.5-turbo"]
}
}
🤖 AI Agent Integration
MCP Manager includes a built-in AI Agent that:
- Registers OpenAI-compatible APIs: Configure via
baseUrland API key - Provides Proxy: Servers can use AI without direct API key access
- Token Statistics: Track all AI usage transparently
- Permission-Based: Each server must have AI Agent access enabled in permissions
How It Works:
-
Register AI Provider in MCP Manager:
- Base URL:
https://api.openai.com/v1 - API Key: (stored securely in OS keychain)
- Model:
gpt-4,gpt-3.5-turbo, etc.
- Base URL:
-
Enable for Server: In server permissions, enable AI Agent access
-
Use in Server: The SDK provides methods to access the AI Agent:
const aiResponse = await server.getAiAgent().chat({ model: 'gpt-4', messages: [{ role: 'user', content: 'Generate image prompt' }] }); -
Track Usage: All token usage is tracked and displayed in MCP Manager
Benefits:
- ✅ No API keys exposed to servers
- ✅ Centralized AI usage tracking
- ✅ Easy to switch AI providers
- ✅ Cost monitoring
🛠️ Available Tools
Image Processing
image_process_local- Process local image: resize, crop, convert format, optimizeimage_analyze- Analyze local image: dimensions, format, file size, metadataimage_optimize- Automatically optimize local image: compress, convert to best formatimage_create_placeholder- Create placeholder image with dimensions displayedimage_create_favicon- Create favicon from image (multiple sizes)image_add_watermark- Add watermark to image (text or image)image_apply_filters- Apply filters: blur, sharpen, grayscale, sepia, brightness, contrastimage_rotate- Rotate image by specified angleimage_crop_custom- Crop image by exact coordinates
Stock Images
images_provider_status- Check status of image providersstock_images_search- Search for images from Pexels or Pixabaystock_images_download_to_project- Download and save image from provider to project
AI Generation
ai_generate_image- Generate image using OpenAI DALL-E
Color Extraction
image_extract_colors_local- Extract dominant colors and color palette from local imagegenerate_color_palette_image- Generate visual color palette image from local image
📚 Example Usage
Example 1: Search and Download Stock Image
# 1. Search for images
# Tool: stock_images_search
# Query: "cozy coffee shop interior"
# 2. Download image to project
# Tool: stock_images_download_to_project
# Photo ID: 123456
# Target Path: public/images/hero.webp
# Format: webp
# Max Width: 1920
Example 2: Process Local Image
# Tool: image_process_local
# Image Path: public/images/photo.jpg
# Output Path: public/images/photo-optimized.webp
# Format: webp
# Max Width: 1920
# Quality: 85
Example 3: Generate AI Image
# Tool: ai_generate_image
# Prompt: "a cozy coffee shop interior with warm lighting"
# Size: large (1024x1024px)
# Target Path: public/images/generated.webp
# Format: webp
🔧 Environment Variables
All environment variables are optional with sensible defaults:
# Server settings
MCP_PORT=3848 # Server port (default: 3848)
MCP_HOST=0.0.0.0 # Server host (default: 0.0.0.0)
MCP_PATH=/mcp # MCP endpoint path (default: /mcp)
MCP_PROJECT_ROOT=/path # Project root directory
# Configuration (alternative to config file)
DEFAULT_PROVIDER=pexels
DEFAULT_FORMAT=webp
DEFAULT_MAX_WIDTH=1920
DEFAULT_QUALITY=80
SAVE_METADATA=true
EMBED_EXIF=false
# API Keys (required for stock images and AI generation)
SECRET_PEXELS_API_KEY=your_key
SECRET_PIXABAY_API_KEY=your_key
SECRET_OPENAI_API_KEY=your_key
SECRET_OPENAI_ORGANIZATION_ID=your_org_id
🏗️ Built on @tscodex/mcp-sdk
This project is built on top of @tscodex/mcp-sdk, which provides:
- ✅ MCP Server Infrastructure: HTTP transport, protocol handling, request routing
- ✅ Authentication & Session Management: Secure session handling
- ✅ Configuration Loading: CLI args, env vars, config files with priority system
- ✅ Secrets Management:
SECRET_*environment variable handling - ✅ Workspace Context: Automatic workspace root detection and header handling
- ✅ AI Agent Integration: Built-in support for AI Agent proxy
- ✅ Type Safety: Full TypeScript support with TypeBox schemas
Key Features of the SDK:
- Fast HTTP-based MCP server creation
- No database required - stateless design
- Works with or without MCP Manager
- Automatic workspace context from headers
- JSON Schema-based configuration
🧪 Development
# Clone repository
git clone https://github.com/unbywyd/tscodex-mcp-images.git
cd tscodex-mcp-images
# Install dependencies
npm install
# Build
npm run build
# Run in development mode
npm run dev
# Run production build
npm start
# Get metadata (for MCP Manager)
npm run meta
📁 Project Structure
cursor-stock-images-mcp-v2/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # Server setup
│ ├── config.ts # Configuration schema
│ ├── config-loader.ts # Config loading logic
│ ├── tools/ # MCP tools
│ │ ├── image-processing.ts
│ │ ├── stock-images.ts
│ │ ├── ai-generation.ts
│ │ └── color-extraction.ts
│ ├── providers/ # Image providers
│ │ ├── pexels.ts
│ │ ├── pixabay.ts
│ │ └── openai.ts
│ ├── image-processor.ts # Image processing logic
│ ├── color-extractor.ts # Color extraction logic
│ └── utils.ts # Utilities
├── dist/ # Compiled JavaScript
├── package.json
└── README.md
📋 Requirements
- Node.js >= 18.0.0
- API keys for providers (optional, but required for stock images and AI generation)
🔗 Related Projects
- MCP Manager - Desktop application for MCP server management
- MCP Manager Bridge - VS Code/Cursor extension bridge
- @tscodex/mcp-sdk - SDK for building MCP servers
- MCP Images (this project) - Image processing MCP server
📄 License
MIT
👤 Author
Website: tscodex.com
🔗 Links
- GitHub: https://github.com/unbywyd/tscodex-mcp-images
- NPM: https://www.npmjs.com/package/@tscodex/mcp-images
- Issues: https://github.com/unbywyd/tscodex-mcp-images/issues
- MCP SDK: https://www.npmjs.com/package/@tscodex/mcp-sdk
- MCP Manager: https://github.com/unbywyd/tscodex-mcp-manager-app
- MCP Bridge: https://github.com/unbywyd/tscodex-mcp-manager-bridge