@tscodex/mcp-images

v0.2.5

Published

11 days ago

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.

0High
0Medium
0Low

unbywyd

mcp mcp-server tscodex-mcp-provider mcp-gateway model-context-protocol cursor ai npx pexels pixabay images photos

@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

📦 MCP Manager | 🌉 MCP Bridge

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 npx or npm, 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-images as 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-images in 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 use MCP_PROJECT_ROOT environment variable (managed mode)
- Use absolute path for standalone mode
defaultProvider ("pexels" | "pixabay" | "openai" | "auto", default: "auto"): Default image provider
defaultFormat ("webp" | "jpeg" | "png" | "avif", default: "webp"): Default image format
defaultMaxWidth (number, default: 1920): Default maximum width (1-10000)
defaultQuality (number, default: 80): Default quality (1-100)
saveMetadata (boolean, default: true): Save JSON metadata alongside images
embedExif (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 baseUrl and 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.
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, optimize
image_analyze - Analyze local image: dimensions, format, file size, metadata
image_optimize - Automatically optimize local image: compress, convert to best format
image_create_placeholder - Create placeholder image with dimensions displayed
image_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, contrast
image_rotate - Rotate image by specified angle
image_crop_custom - Crop image by exact coordinates

Stock Images

images_provider_status - Check status of image providers
stock_images_search - Search for images from Pexels or Pixabay
stock_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 image
generate_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

unbywyd

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@tscodex/mcp-images

🚀 Quick Links

🎯 What is This?

Architecture Overview

How It Works

🎨 Features

📦 Installation

Option 1: Standalone (via npx)

Option 2: Global Installation

Option 3: Managed Mode (Recommended)

🚀 Quick Start

Standalone Mode

Managed Mode

⚙️ Configuration

Configuration File

Secrets Management

🔒 Security & Permissions

Security Features

Permissions System

🤖 AI Agent Integration

🛠️ Available Tools

Image Processing

Stock Images

AI Generation

Color Extraction

📚 Example Usage

Example 1: Search and Download Stock Image

Example 2: Process Local Image

Example 3: Generate AI Image

🔧 Environment Variables

🏗️ Built on @tscodex/mcp-sdk

🧪 Development

📁 Project Structure

📋 Requirements

🔗 Related Projects

📄 License

👤 Author

🔗 Links