bahadirbklg/layer-ai-mcp-server

Layer.ai MCP Server

A Model Context Protocol (MCP) server for generating game assets using Layer.ai's AI platform. Generate sprites, characters, backgrounds, and other 2D assets directly from your development environment.

Made with AI - Use with caution

Features

• Asset Generation: Generate 2D game assets using Layer.ai Forge
• Prompt Optimization: Optimize prompts with Layer.ai Prompt Genie
• Usage Tracking: Monitor usage against free tier limits (600 assets)
• Workspace Management: Export and manage workspace data
• Asset Refinement: Refine and modify existing assets
• Auto-Save: Automatically save generated assets to your project
• Error Handling: Robust error handling with automatic retries
• Quota Protection: Prevents exceeding your free tier limit

Installation

Prerequisites

• Python 3.10+ (required for MCP compatibility)
• Git for cloning the repository
• Layer.ai account and API token

Quick Install (Recommended)

# Clone the repository
git clone https://github.com/bahadirbklg/layer-ai-mcp-server.git
cd layer-ai-mcp-server

# Run the installation script
chmod +x install.sh
./install.sh

Manual Installation

# Clone the repository
git clone https://github.com/bahadirbklg/layer-ai-mcp-server.git
cd layer-ai-mcp-server

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

# Create assets directory
mkdir -p assets

# Set up credentials
python layer-mcp-server/setup.py

Installation Options

• Production: pip install -r requirements.min.txt (core dependencies only)
• Development: pip install -r requirements.dev.txt (includes testing and linting tools)
• Full: pip install -r requirements.txt (recommended for most users)

Verify Installation

Test your installation to make sure everything is working:

# Run the installation test
python3 verify-install.py

This will check:

• Python version compatibility (3.10+)
• All required dependencies are installed
• Project files are in place
• Main server can be imported successfully

Configuration

Environment Variables

Create a .env file or set environment variables:

# Required: Your Layer.ai API token
LAYER_API_TOKEN=pat_your_token_here

# Optional: API base URL (defaults to https://api.layer.ai)
LAYER_API_BASE_URL=https://api.layer.ai

# Optional: Usage tracking file (defaults to .layer_usage.json)
LAYER_USAGE_FILE=.layer_usage.json

# Optional: Default save directory (defaults to ./assets)
LAYER_DEFAULT_SAVE_DIR=./assets

# Optional: Default workspace ID
LAYER_WORKSPACE_ID=your_workspace_id

Getting Your API Token

1. Sign up at Layer.ai
2. Go to your account settings
3. Generate a new API token (starts with pat_)
4. Copy the token to your .env file

MCP Client Configuration

For Kiro IDE

Add to your MCP client configuration:

{
  "mcpServers": {
    "layer-ai-comprehensive": {
      "command": "python",
      "args": ["layer-mcp-server/server.py"],
      "env": {
        "LAYER_API_TOKEN": "pat_your_token_here",
        "LAYER_WORKSPACE_ID": "your_workspace_id"
      },
      "disabled": false,
      "timeout": 180,
      "autoApprove": [
        "create_asset", "remove_background", "describe_image", 
        "generate_prompt", "get_workspace_info"
      ]
    }
  }
}

For Claude Desktop

Add to your Claude Desktop MCP configuration file:

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

{
  "mcpServers": {
    "layer-ai": {
      "command": "python",
      "args": ["path/to/layer-mcp-server/server.py"],
      "env": {
        "LAYER_API_TOKEN": "pat_your_token_here",
        "LAYER_WORKSPACE_ID": "your_workspace_id"
      }
    }
  }
}

Usage

Available Tools

1. create_asset - Generate Assets

Generate sprites, characters, backgrounds, and other assets.

Parameters:

• prompt (required): Description of the asset to generate
• generation_type (optional): CREATE, UPSCALE, etc.
• width/height (optional): Output dimensions (default: 512x512)
• quality (optional): LOW, MEDIUM, HIGH (default: HIGH)
• transparency (optional): Enable transparent backgrounds
• save_path (optional): Local path to save the asset

Example:

{
  "prompt": "A cute pixel art character for a platformer game",
  "generation_type": "CREATE",
  "width": 512,
  "height": 512,
  "transparency": true,
  "save_path": "./sprites/player_character.png"
}

2. get_workspace_info - Check Status

Get information about your Layer.ai workspace and available features.

3. remove_background - Background Removal (In Development)

Remove backgrounds from existing images using AI.

4. describe_image - Image Analysis (In Development)

Get AI-generated descriptions of images.

5. generate_prompt - Prompt Optimization (In Development)

Optimize your prompts using Layer.ai's Prompt Genie.

Usage Examples

Generate a Game Sprite

# Create a transparent character sprite
create_asset(
    prompt="fantasy warrior character, pixel art, 64x64, RPG game",
    generation_type="CREATE",
    width=64,
    height=64,
    transparency=True,
    save_path="./assets/warrior_sprite.png"
)

Create a Tileable Texture

# Generate seamless stone texture
create_asset(
    prompt="medieval stone brick wall, seamless texture",
    generation_type="CREATE", 
    width=256,
    height=256,
    tileability=True,
    save_path="./assets/stone_texture.png"
)

Project Structure

layer-ai-mcp-server/
├── layer-mcp-server/
│   ├── server.py                            # Main MCP server
│   ├── auth.py                              # Authentication & token management
│   ├── setup.py                             # Interactive credential setup
│   ├── api-docs.md                          # API documentation
│   ├── mcp-config.md                        # MCP configuration guide
│   ├── security.md                          # Security documentation
│   └── pyproject.toml                       # Package configuration
├── assets/                                  # Generated assets (auto-created)
├── README.md                                # Main documentation
├── .gitignore                               # Git ignore patterns
├── requirements.txt                         # Core dependencies
├── requirements.min.txt                     # Minimal dependencies
├── requirements.dev.txt                     # Development dependencies
├── install.sh                               # Installation script
├── verify-install.py                        # Installation verification
├── setup.py                                 # Package setup
└── LICENSE                                  # MIT License

Issues & Bug Tracking

Open Issues

High Priority

• [BUG-001] Timeout issues with complex asset generation (>60s)
  • Status: RESOLVED (Fixed with 180s timeout in MCP config)
  • Solution: Added "timeout": 180 to MCP server configuration
  • Date: 2025-08-15

Medium Priority

• [FEATURE-001] Background removal feature not implemented

  • Status: IN PROGRESS
  • Description: remove_background tool returns "implementation in progress"
  • Date: 2025-08-15

• [FEATURE-002] Image description feature not implemented

  • Status: IN PROGRESS
  • Description: describe_image tool returns "implementation in progress"
  • Date: 2025-08-15

• [FEATURE-003] Prompt generation feature not implemented

  • Status: IN PROGRESS
  • Description: generate_prompt tool returns "implementation in progress"
  • Date: 2025-08-15

Known Limitations

1. Free Tier Limits: 600 assets per month on free tier
2. File Size Limits: Large assets (>10MB) may have slower processing
3. Network Dependency: Requires stable internet connection for Layer.ai API
4. Python Version: Requires Python 3.10+ for full compatibility

Feature Requests

• 3D Asset Generation: Support for generating 3D models and textures
• Animation Support: Generate sprite animations and sequences
• Style Transfer: Apply artistic styles to existing assets
• Bulk Operations: Process multiple assets simultaneously
• Asset Versioning: Track and manage different versions of assets

Troubleshooting

Common Issues

"Invalid API token"

• Check your .env file has the correct LAYER_API_TOKEN
• Ensure the token starts with pat_
• Verify the token is valid in your Layer.ai account

"Quota exceeded"

• Check usage with get_workspace_info tool
• You've reached the 600 asset limit for free tier
• Consider upgrading your Layer.ai plan

"Network errors"

• Check your internet connection
• Verify Layer.ai API is accessible
• The server automatically retries failed requests

"MCP connection issues"

• Ensure you're running the server correctly
• Check MCP client configuration
• Review server logs for detailed error messages

"Timeout errors"

• Increase timeout in MCP configuration: "timeout": 180
• Complex assets may take 30-60 seconds to generate
• Check network stability for long-running operations

"Installation errors"

• Python version: Ensure you have Python 3.10+ (python3 --version)
• Virtual environment: Use a virtual environment to avoid conflicts
• Permissions: On Linux/macOS, you may need chmod +x install.sh
• Dependencies: Try pip install --upgrade pip before installing requirements
• MCP compatibility: Some older Python versions may have MCP compatibility issues

"Import errors"

• Missing dependencies: Run pip install -r requirements.txt again
• Virtual environment: Make sure your virtual environment is activated
• Path issues: Ensure you're running from the correct directory
• Token manager: If token_manager import fails, run the setup script

Issue Reporting Template

When reporting new issues, please use this format:

**[TYPE-###]** Brief description
- **Status**: NEW/IN PROGRESS/RESOLVED
- **Priority**: High/Medium/Low
- **Description**: Detailed description of the issue
- **Steps to Reproduce**: 
  1. Step one
  2. Step two
  3. Expected vs actual result
- **Environment**: 
  - OS: [Windows/macOS/Linux]
  - Python version: [3.x.x]
  - MCP Client: [Claude Desktop/Other]
- **Date**: YYYY-MM-DD

Issue Types:

• BUG - Something is broken
• FEATURE - New functionality needed
• ENHANCEMENT - Improvement to existing feature
• DOCS - Documentation issue
• PERFORMANCE - Performance problem

Security

This project uses secure credential management:

• AES-256 Encryption: API tokens encrypted at rest
• PBKDF2 Key Derivation: Secure key generation
• File Permissions: Restricted access (600)
• No Version Control Exposure: Credentials never committed

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

Links

• Layer.ai Platform
• Get API Token
• Layer.ai Documentation

Made with AI - Use with caution

Start generating amazing assets for your projects with Layer.ai!