jsoncut-mcp-server

jsoncut/jsoncut-mcp-server

3.2

If you are the rightful owner of jsoncut-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Jsoncut MCP Server is a Model Context Protocol server designed to facilitate the creation of images and videos through the Jsoncut API, enabling AI agents to generate media programmatically.

Tools
5
Resources
0
Prompts
0

[!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

Jsoncut MCP Server

Model Context Protocol server for the Jsoncut API
Enable AI agents to generate stunning images and videos programmatically

🚀 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

📦 Quick Start

Using npx (Recommended for Local)

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

Using Remote Server (Recommended)

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 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

Remote Server (Recommended)

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 file for details.

🔗 Links

Built with the Model Context Protocol SDK by Anthropic

Made with ❤️ by the Jsoncut Team