Skip to main content
Glama
WARNING

โš ๏ธ OUTDATED REPOSITORY - This repository is no longer maintained

A public MCP server is now available and this package is deprecated.
Please use the official public server instead: https://mcp.jsoncut.com/mcp

For more information, see: https://docs.jsoncut.com/docs/mcp/overview



๐Ÿš€ Features

  • ๐ŸŽจ Image Generation: Create JSON configurations for image composition with layers, positioning, and effects

  • ๐ŸŽฌ Video Generation: Create JSON configurations for video rendering with clips, transitions, and audio

  • โœ… Configuration Validation: Validate configs against the Jsoncut API before submission

  • ๐Ÿ“‹ Schema Resources: JSON schemas automatically available as MCP resources

  • ๐Ÿ”‘ Flexible Authentication: API key via environment variable or .env file


Related MCP server: CapCut & Google Flow MCP

๐Ÿ“ฆ Quick Start

export JSONCUT_API_KEY=your_api_key_here
npx -y @jsoncut/mcp-server

A public MCP server is available at https://mcp.jsoncut.com. No installation needed - just configure your MCP client with your API key:

{
  "jsoncut": {
    "url": "https://mcp.jsoncut.com/mcp",
    "headers": {
      "x-api-key": "your_jsoncut_api_key_here"
    }
  }
}

Using Docker Locally (Optional)

You can also run your own local server using Docker:

# Pull and run from Docker Hub
docker run -d \
  --name jsoncut-mcp \
  -p 3210:3000 \
  centerbit/jsoncut-mcp-server:latest

# Access at: http://localhost:3210/mcp

Or use Docker Compose:

# Start the service
docker-compose up -d

# Access at: http://localhost:3210/mcp

๐Ÿ“– See DOCKER.md for complete Docker deployment guide

Get Your API Key

Get your Jsoncut API key at jsoncut.com

# Set as environment variable
export JSONCUT_API_KEY=your_api_key_here

# Or create .env file
cp .env.example .env
# Edit .env and add: JSONCUT_API_KEY=your_api_key_here

๐ŸŽฏ MCP Client Configuration

Use the public server at https://mcp.jsoncut.com:

Cursor IDE

Open Cursor Settings โ†’ Features โ†’ MCP Servers โ†’ "+ Add New MCP Server"

{
  "jsoncut": {
    "url": "https://mcp.jsoncut.com/mcp",
    "headers": {
      "X-API-Key": "your_jsoncut_api_key_here"
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "jsoncut": {
      "url": "https://mcp.jsoncut.com/mcp",
      "headers": {
        "X-API-Key": "your_jsoncut_api_key_here"
      }
    }
  }
}

Local npx Mode

For local development without network access:

Cursor IDE

{
  "jsoncut": {
    "command": "npx",
    "args": ["-y", "@jsoncut/mcp-server"],
    "env": {
      "JSONCUT_API_KEY": "your_api_key_here"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "jsoncut": {
      "command": "npx",
      "args": ["-y", "@jsoncut/mcp-server"],
      "env": {
        "JSONCUT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Local Docker Server

If you're running your own local Docker server:

Cursor IDE

{
  "jsoncut": {
    "url": "http://localhost:3210/mcp",
    "headers": {
      "X-API-Key": "your_jsoncut_api_key_here"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "jsoncut": {
      "url": "http://localhost:3210/mcp",
      "headers": {
        "X-API-Key": "your_jsoncut_api_key_here"
      }
    }
  }
}

๐Ÿ“š MCP Resources

The server automatically exposes JSON schemas as MCP resources:

  • schema://image - Complete image generation schema

  • schema://video - Complete video generation schema

AI agents can read these directly without tool calls for fast access to all configuration options.


๐Ÿ› ๏ธ Available Tools

create_image_config

Create JSON configurations for image generation with a layer-based system.

Layer Types:

  • image: Display images with fit modes (cover, contain, fill, inside, outside)

  • text: Text with custom fonts, alignment, wrapping, and effects

  • rectangle: Rectangular shapes with fill, stroke, and rounded corners

  • circle: Circular and elliptical shapes

  • gradient: Linear or radial color gradients

Positioning:

  • Pixel coordinates: { x: 100, y: 50 }

  • Position strings: center, top, bottom, top-left, top-right, etc.

  • Position objects: { x: 0.5, y: 0.5, originX: "center", originY: "center" }

Example:

{
  "width": 1200,
  "height": 630,
  "layers": [
    {
      "type": "gradient",
      "x": 0, "y": 0, "width": 1200, "height": 630,
      "gradient": {
        "type": "linear",
        "colors": ["#667eea", "#764ba2"],
        "direction": "diagonal"
      }
    },
    {
      "type": "text",
      "text": "Welcome to Jsoncut",
      "position": "center",
      "fontSize": 64,
      "color": "#ffffff"
    }
  ]
}

create_video_config

Create JSON configurations for video generation with clips, layers, and transitions.

Key Features:

  • Clips: Sequential video segments with individual layers

  • Layer Types: video, image, title, subtitle, news-title, audio, gradients, and more

  • Transitions: 75+ effects (fade, wipe, circle, cube, glitch, zoom, etc.)

  • Audio: Background music, multiple tracks, normalization, and ducking

Example:

{
  "width": 1920,
  "height": 1080,
  "fps": 30,
  "defaults": {
    "duration": 3,
    "transition": { "name": "fade", "duration": 1 }
  },
  "clips": [
    {
      "layers": [
        { "type": "title", "text": "Welcome", "position": "center" }
      ]
    }
  ]
}

validate_config

Validate configurations against the Jsoncut API before submission.

Parameters:

  • type: "image" or "video"

  • config: Configuration object to validate

  • apiKey: Optional API key (uses environment if not provided)

Returns:

  • Validation status

  • Estimated token cost

  • Error details (if any)

  • Detected resources with sizes

get_image_schema / get_video_schema

Get complete JSON schemas for image or video generation.

Note: Schemas are also available as MCP resources (schema://image and schema://video) which AI agents can access directly without tool calls.


๐Ÿ“– Workflow

  1. Create Configuration: Use create_image_config or create_video_config

  2. Validate (optional): Call validate_config if you have actual file paths

  3. Submit: Use the configuration with the Jsoncut API

The schemas are automatically available as MCP resources, so AI agents have instant access to all configuration options.


๐Ÿ“ File Paths

Use placeholder paths in configurations:

/image/2024-01-15/userXXX/photo.jpg
/video/2024-01-15/userXXX/video.mp4
/audio/2024-01-15/userXXX/music.mp3
/font/2024-01-15/userXXX/CustomFont.ttf

Supported formats:

  • Images: png, jpg, jpeg, gif, webp

  • Videos: mp4, mov, avi, webm

  • Audio: mp3, wav, m4a, aac

  • Fonts: ttf, otf, woff, woff2


๐Ÿงช Testing

Use the MCP Inspector for interactive testing:

export JSONCUT_API_KEY=your_api_key_here
npm run inspector

๐Ÿ”ง Development

Local Development

# Clone and install
git clone https://github.com/jsoncut/jsoncut-mcp-server.git
cd jsoncut-mcp-server
npm install

# Build
npm run build

# Watch mode
npm run watch

# Run locally
node dist/index.js

Configuration with Local Build

For Cursor/Claude Desktop, use the local build:

{
  "jsoncut": {
    "command": "node",
    "args": ["/absolute/path/to/jsoncut-mcp-server/dist/index.js"],
    "env": {
      "JSONCUT_API_KEY": "your_api_key_here"
    }
  }
}

๐Ÿ“ Examples

See the examples/ directory for complete configurations:

  • image-example.json - Image generation with multiple layer types

  • video-example.json - Video generation with clips and transitions


๐Ÿค Contributing

Contributions are welcome! Please feel free to submit a Pull Request.


๐Ÿ“„ License

MIT License - see LICENSE file for details.



Available Tools

5 tools
create_image_configA

Create a JSON configuration for image generation based on jsoncut documentation.

Returns a complete configuration object that can be used with the validate_config tool or submitted directly to the jsoncut API.

WORKFLOW:

  1. First get the schema (read resource schema://image or call get_image_schema) to understand all available options

  2. Create the configuration with this tool

  3. Call validate_config to verify the configuration (if user provided media file paths)

Image Structure:

  • Layer-based system (rendered bottom to top, max 50 layers)

  • Canvas with dimensions, background color, and output format

  • Support for defaults to avoid repetition

Layer Types:

  • image: Display uploaded images with fit modes (cover, contain, fill, inside, outside)

  • text: Text with custom fonts, alignment, wrapping, and effects

  • rectangle: Rectangular shapes with fill, stroke, and rounded corners

  • circle: Circular and elliptical shapes

  • gradient: Linear or radial color gradients

Positioning Options:

  • x, y coordinates (pixels from top-left)

  • position strings: center, top, bottom, top-left, top-right, center-left, center-right, bottom-left, bottom-right

  • position objects: { x: 0-1, y: 0-1, originX: left|center|right, originY: top|center|bottom }

Visual Effects:

  • opacity: 0-1 transparency

  • rotation: degrees

  • blur: pixel radius

  • borderRadius: rounded corners (image, rectangle)

Text Features:

  • Custom fonts via fontPath or Google Fonts via googleFont (format: 'FontName:weight' e.g. 'Roboto:600')

  • Text wrapping with width and lineHeight

  • Alignment: left, center, right

  • backgroundColor (single line only)

Output Formats:

  • png: Lossless with transparency (default)

  • jpeg: Lossy compression (use quality parameter)

  • webp: Modern format with transparency and compression

Defaults System:

  • defaults.layer: Properties for all layers

  • defaults.layerType.{type}: Properties for specific layer types

File paths should be placeholders like "/image/2024-01-15/userXXX/filename.ext" or "/font/2024-01-15/userXXX/font.ttf".

Inputs: layers (required), width, height, backgroundColor, +3 more.

create_video_configA

Create a JSON configuration for video generation based on jsoncut documentation.

Returns a complete configuration object that can be used with the validate_config tool or submitted directly to the jsoncut API.

WORKFLOW:

  1. First get the schema (read resource schema://video or call get_video_schema) to understand all available options

  2. Create the configuration with this tool

  3. Call validate_config to verify the configuration (if user provided media file paths)

Video Structure:

  • Built using clips (segments) that play sequentially

  • Each clip contains layers (rendered bottom to top)

  • Supports transitions between clips

  • Comprehensive audio system with multiple options

Layer Types:

  • video: Display video files with timing control, Ken Burns effects, and enhanced positioning

  • image: Static images with positioning and Ken Burns effects

  • image-overlay: Images positioned over other content with timing

  • title: Large headline text with animation styles (fade-in, word-by-word, letter-by-letter) and enhanced positioning

  • subtitle: Smaller text for captions

  • news-title: Breaking news style with colored backgrounds

  • title-background: Titles with full-screen backgrounds

  • slide-in-text: Animated text that slides in

  • audio: Audio tracks tied to clips (requires keepSourceAudio: true)

  • detached-audio: Audio with clip-relative timing

  • fill-color: Solid color backgrounds

  • linear-gradient: Linear gradient backgrounds

  • radial-gradient: Radial gradient backgrounds

  • rainbow-colors: Animated rainbow effects

  • pause: Black screen pauses

Audio Options:

  • audioFilePath + loopAudio: Background music throughout video

  • audioTracks: Multiple audio tracks with independent timing

  • audioNorm: Audio normalization with ducking

  • keepSourceAudio: Keep audio from video layers

  • Audio layers within clips

Video & title layer Positioning:

  • Position objects: { x: 0-1, y: 0-1, originX: left|center|right, originY: top|center|bottom }

  • Position strings: center, top, bottom, top-left, top-right, center-left, center-right, bottom-left, bottom-right

  • Video layers support both position objects and strings

  • Title layers support enhanced positioning with position objects

Title Layer Animation Styles:

  • fade-in: Smooth fade-in effect (default)

  • word-by-word: Words appear sequentially

  • letter-by-letter: Letters appear sequentially

  • Zoom effects automatically disabled for word-by-word and letter-by-letter styles

Transitions: 75+ transition effects including fade, wipe, circle, cube, glitch, zoom, etc.

File paths should be placeholders like "/input/userXXX/filename.ext".

Inputs: clips (required), width, height, fps, +10 more.

get_image_schemaA

Get the complete JSON schema for image generation.

Returns the full JSON Schema document that defines all possible configuration options for image generation jobs. Use this to understand all available options, constraints, and examples.

NOTE: This schema is also available as a resource at schema://image which can be read directly without a tool call.

IMPORTANT: Get this schema FIRST when creating image configurations to understand the complete structure, available layer types, positioning options, and all properties. This ensures you create valid and complete configurations.

Inputs: no named parameters.

get_video_schemaA

Get the complete JSON schema for video generation.

Returns the full JSON Schema document that defines all possible configuration options for video generation jobs. Use this to understand all available options, constraints, and examples.

NOTE: This schema is also available as a resource at schema://video which can be read directly without a tool call.

IMPORTANT: Get this schema FIRST when creating video configurations to understand the complete structure, available layer types, audio options, transitions, and all properties. This ensures you create valid and complete configurations.

Inputs: no named parameters.

validate_configA

Validate a job configuration against the jsoncut API.

This tool sends the configuration to the API's validation endpoint to check:

  • Schema compliance

  • Resource availability

  • Estimated token cost

  • Any configuration errors

WHEN TO USE:

  • ONLY call this tool if the user has provided actual media file paths (e.g., from uploaded files)

  • DO NOT validate configurations with placeholder paths like "/image/2024-01-15/userXXX/..."

  • Always call this after creating a configuration when real file paths are available

BENEFITS:

  • Catches errors before job submission

  • Provides accurate token cost estimates

  • Verifies that referenced files exist and are accessible

Inputs: type (required), config (required), apiKey.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: two for image config/schema, two for video config/schema, and one for validation. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (create_, get_, validate_), with parallelism between image and video tools.

    Tool Count5/5

    5 tools is well-scoped for the server's purpose of handling image and video configuration creation, schema retrieval, and validation. No extraneous tools.

    Completeness4/5

    Core workflow is covered: schema retrieval, config creation, and validation. Minor gaps include lack of a tool to submit jobs or manage existing configs, but these may be out of scope.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers