@tscodex/mcp-images
Advanced tools
MCP server with comprehensive image processing tools - resize, crop, optimize, extract colors, apply filters, create placeholders and more. Optional integration with Pexels and Pixabay for image search and download.
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.
Desktop application for managing MCP servers | VS Code/Cursor extension bridge
This is an MCP server built on the @tscodex/mcp-sdk that provides powerful image processing capabilities. It can work in two ways:
npx or npm, passing environment variables and configuration┌─────────────────────────────────────────────────────────────┐
│ 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) │
└─────────────────────────┘
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:
@tscodex/mcp-images)The Bridge: MCP Manager Bridge automatically:
mcp.jsonnpx @tscodex/mcp-images@latest
npm install -g @tscodex/mcp-images
Use with MCP Manager for the best experience:
@tscodex/mcp-images as a new serverBenefits of Managed 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
mcp.json@tscodex/mcp-images in the Bridge panelCreate .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
"." to use MCP_PROJECT_ROOT environment variable (managed mode)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⚠️ 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:
This allows fine-grained control over what secrets each server can access.
Get API Keys:
MCP Manager provides enterprise-grade security:
MCP Manager's permission system allows you to configure:
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"]
}
}
MCP Manager includes a built-in AI Agent that:
baseUrl and API keyHow It Works:
Register AI Provider in MCP Manager:
https://api.openai.com/v1gpt-4, gpt-3.5-turbo, etc.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:
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 coordinatesimages_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 projectai_generate_image - Generate image using OpenAI DALL-Eimage_extract_colors_local - Extract dominant colors and color palette from local imagegenerate_color_palette_image - Generate visual color palette image from local 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
# Tool: image_process_local
# Image Path: public/images/photo.jpg
# Output Path: public/images/photo-optimized.webp
# Format: webp
# Max Width: 1920
# Quality: 85
# Tool: ai_generate_image
# Prompt: "a cozy coffee shop interior with warm lighting"
# Size: large (1024x1024px)
# Target Path: public/images/generated.webp
# Format: webp
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
This project is built on top of @tscodex/mcp-sdk, which provides:
SECRET_* environment variable handlingKey Features of the SDK:
# 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
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
MIT
Website: tscodex.com
FAQs
MCP server with comprehensive image processing tools - resize, crop, optimize, extract colors, apply filters, create placeholders and more. Optional integration with Pexels and Pixabay for image search and download.
We found that @tscodex/mcp-images demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh joins Software Engineering Daily to discuss modern software supply chain attacks and rising AI-driven security risks.
Security News
GitHub has revoked npm classic tokens for publishing; maintainers must migrate, but OpenJS warns OIDC trusted publishing still has risky gaps for critical projects.
Security News
Rust’s crates.io team is advancing an RFC to add a Security tab that surfaces RustSec vulnerability and unsoundness advisories directly on crate pages.