Skip to main content
Glama

VibeTide MCP Server

A Model Context Protocol (MCP) server for creating, editing, and playing VibeTide 2D platformer levels. This server provides tools for level manipulation, visualization, and gameplay through the MCP protocol.

VibeTide Hero Image

License: MIT Python 3.10+ PyPI version

🎮 Screenshots & Demo

Level Creation and Editing

VibeTide Level Creation Create beautiful 2D platformer levels with AI assistance

Gameplay Preview

VibeTide Gameplay Play your created levels in the web player

Related MCP server: agent-game-engine

Features

  • Level Creation: Create new VibeTide levels with AI assistance

  • Level Editing: Edit entire levels, single rows, or individual tiles

  • Level Visualization: Generate ASCII and PNG visualizations of levels

  • Level Playing: Get URLs to play levels in the web player

  • Level Decoding: Decode levels from sharing URLs

  • Metadata Management: Edit level properties like spawn rates and difficulty

Installation

Installing via Smithery

To install VibeTide Level Editor Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @banjtheman/vibe_tide_mcp --client claude

If you have uvx installed, you can run the server directly without local installation:

uvx --from vibe-tide-mcp-server vibe-tide-mcp-server

Option 2: Local Installation

  1. Clone the repository:

git clone https://github.com/banjtheman/vibe_tide_mcp.git
cd vibe_tide_mcp
  1. Install dependencies:

pip install -r requirements.txt
  1. Make the server executable:

chmod +x vibe_tide_mcp_server.py

Configuration

MCP Client Configuration

Add the server to your MCP client configuration:

Local Python Server

{
  "mcpServers": {
    "vibe-tide": {
      "command": "python",
      "args": ["/path/to/vibe_tide_mcp_server.py"],
      "env": {}
    }
  }
}

Using UVX

{
  "mcpServers": {
    "vibe-tide": {
      "command": "uvx",
      "args": [
        "--from", "vibe-tide-mcp-server", "vibe-tide-mcp-server"
      ],
      "env": {}
    }
  }
}

Available Tools

Level Viewing Tools

  • view_level: View level data with ASCII visualization

  • view_level_image: Generate beautiful PNG visualizations

  • decode_level_from_url: Decode levels from sharing URLs

  • get_tile_reference: Get reference guide for tile types

Level Playing Tools

  • play_level: Get URL to play level in web player

Level Editing Tools

  • edit_level_tile: Edit a single tile

  • edit_level_row: Edit an entire row

  • edit_entire_level: Replace all tiles in a level

  • edit_level_metadata: Edit level properties (name, spawn rates, etc.)

Level Creation Tools

  • create_level: Create new levels with AI assistance

Tile Types

Type

Symbol

Name

Description

0

⬜

Empty

Walkable air space

1

🌱

Grass

Standard ground platform

2

🗿

Rock

Solid stone platform

3

⭐

Yellow

Special yellow platform

4

❄️

Ice

Slippery ice platform

5

🔥

Red

Dangerous red platform

6

⚠️

Spikes

Hazardous spikes

7

💧

Water

Water tiles

Examples

Creating a New Level

# Create a simple level with platforms
level_tiles = [
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],  # Empty top row
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],  # Empty row
    [0, 0, 0, 1, 1, 1, 0, 0, 0, 0],  # Grass platform
    [1, 1, 0, 0, 0, 0, 0, 1, 1, 1],  # Ground platforms
    [2, 2, 2, 2, 2, 2, 2, 2, 2, 2],  # Rock foundation
]

result = create_level(
    level_name="My First Level",
    description="A simple starter level",
    tiles=level_tiles,
    width=10,
    height=5,
    maxEnemies=3,
    enemySpawnChance=10.0,
    coinSpawnChance=20.0
)

Editing a Level

# Edit a single tile
result = edit_level_tile(
    encoded_level="your_encoded_level_here",
    row=2,
    col=5,
    new_tile_type=6  # Add spikes
)

# Edit level metadata
result = edit_level_metadata(
    encoded_level="your_encoded_level_here",
    new_name="Updated Level",
    max_enemies=5,
    enemy_spawn_chance=15.0
)

Viewing and Playing Levels

# View level visualization
result = view_level("your_encoded_level_here")
print(result["visualization"])

# Generate PNG image
image_path = view_level_image("your_encoded_level_here")

# Get play URL
result = play_level("your_encoded_level_here")
print(f"Play at: {result['play_url']}")

Development

Running the Server

python vibe_tide_mcp_server.py

Testing

The server includes comprehensive error handling and validation for all level operations.

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests if applicable

  5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Available Tools

10 tools
create_levelA

You are an AI assistant tasked with creating fast, fun, and playable levels for the VibeTide 2D platformer game. Your role is to design levels that are engaging and balanced while adhering to specific rules and guidelines.

Here are the critical rules you must follow:
1. Create levels that are EXACTLY target_width tiles wide and target_height tiles tall (default 50×22).
2. The player must spawn at the LEFTMOST solid platform in the bottom half of the level.
3. Leave 3-4 empty rows above the starting platform for jumping.
4. Design the level as a LEFT-TO-RIGHT platformer, not a maze.

Use the following tile types in your level design:
0 = Empty
1 = Grass
2 = Rock
3 = Yellow
4 = Ice
5 = Red
6 = Spikes
7 = Water

Follow these level design guidelines:
- Bottom half: Focus on main platforms and gameplay elements
- Top half: Keep mostly empty for air and jumping
- Create jumpable gaps (maximum 3-4 tiles apart)
- Ensure a clear left-to-right progression

For difficulty parameters:
- Easy levels: maxEnemies=2-3, enemySpawnChance=5-10, coinSpawnChance=20-30
- Medium levels: maxEnemies=4-6, enemySpawnChance=10-15, coinSpawnChance=15-20
- Hard levels: maxEnemies=7-10, enemySpawnChance=15-25, coinSpawnChance=10-15


Ensure that your level is exactly the specified dimensions and follows all the design rules for playability.

Args:
    level_name: The name of the level
    description: A brief description of the level
    tiles: A 2D array of tile types
    width: The width of the level
    height: The height of the level
    maxEnemies: The maximum number of enemies in the level
    enemySpawnChance: The chance of an enemy spawning
    coinSpawnChance: The chance of a coin spawning

Inputs: level_name (required), description (required), tiles (required), width, +4 more. Returns: result

decode_level_from_urlB

Decode a VibeTide level from an encoded URL string.

Args:
    encoded_level: The encoded level string from a URL or sharing link

Returns the decoded level data with visualization.

Inputs: encoded_level (required). Returns: result

edit_entire_levelB

Edit an entire VibeTide level, replacing all tiles and optionally metadata.

Args:
    level_data: The original level data (for reference)
    new_tiles: 2D array of tile types (each 0-7)
    new_name: New name for the level (optional)
    new_description: New description for the level (optional)
    max_enemies: Maximum enemies parameter (1-10, optional)
    enemy_spawn_chance: Enemy spawn chance percentage (0-100, optional)
    coin_spawn_chance: Coin spawn chance percentage (0-100, optional)

Returns the completely modified level data.

Inputs: level_data (required), new_tiles (required), new_name, new_description, +3 more. Returns: result

edit_level_metadataA

Edit only the metadata of a VibeTide level without changing the tile layout.

This is much more efficient than edit_entire_level when you only want to change
game parameters like enemy count, spawn rates, name, or description.

Args:
    encoded_level: The encoded level string to modify
    new_name: New name for the level (optional)
    new_description: New description for the level (optional)
    max_enemies: Maximum enemies parameter (0-10, optional)
    enemy_spawn_chance: Enemy spawn chance percentage (0-100, optional)
    coin_spawn_chance: Coin spawn chance percentage (0-100, optional)

Returns:
    The modified level data with new encoded string

Inputs: encoded_level (required), new_name, new_description, max_enemies, +2 more. Returns: result

edit_level_rowB

Edit an entire row in a VibeTide level.

Args:
    encoded_level: An encoded level string from a URL or sharing link
    row: Row index to replace (0-based, from top)
    new_row_tiles: Array of tile types for the new row (each 0-7)

Returns the modified level data with the entire row replaced.

Inputs: encoded_level (required), row (required), new_row_tiles (required). Returns: result

edit_level_tileA

Edit a single tile in a VibeTide level.

Args:
    encoded_level: An encoded level string from a URL or sharing link
    row: Row index (0-based, from top)
    col: Column index (0-based, from left)
    new_tile_type: New tile type (0-7, see tile legend)

Returns the modified level data with the single tile changed.

Inputs: encoded_level (required), row (required), col (required), new_tile_type (required). Returns: result

get_tile_referenceA

Get the reference guide for VibeTide tile types.

Returns information about all available tile types and their properties.

Inputs: no named parameters. Returns: result

play_levelB

Get the URL to play a VibeTide level in the web player.

Args:
    encoded_level: An encoded level string for playing

Returns a URL to play the level.

Inputs: encoded_level (required). Returns: result

view_levelC

View a VibeTide level with visual representation.

Args:
    encoded_level: An encoded level string from a URL or sharing link

Returns a visual representation of the level.

Inputs: encoded_level (required). Returns: result

view_level_imageA

View a VibeTide level as a beautiful PNG image with proper colors.

This generates a much better visual representation than the ASCII version,
using the same colors as the web builder. The image is saved to a temporary
file and the file path is returned for MCP clients to display.

Args:
    encoded_level: An encoded level string from a URL or sharing link
    tile_size: Size of each tile in pixels (default 16, will auto-adjust for wide levels)
    max_width: Maximum image width in pixels (default 1200)

Returns:
    The file path to the generated PNG image

Inputs: encoded_level (required), tile_size, max_width. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a distinct purpose with clear boundaries: create_level for initial creation, decode_level_from_url for parsing, edit_entire_level for full replacement, edit_level_metadata for parameter updates, edit_level_row/ tile for granular edits, get_tile_reference for documentation, play_level for launching, and view_level/ view_level_image for visualization. No overlap or ambiguity exists between these functions.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case, such as create_level, edit_level_metadata, and view_level_image. The naming is predictable and readable throughout, with no deviations in style or convention.

    Tool Count5/5

    With 10 tools, the server is well-scoped for level creation and management in a 2D platformer game. Each tool earns its place by covering distinct aspects like creation, editing, visualization, and gameplay, without being overly sparse or bloated.

    Completeness5/5

    The toolset provides complete coverage for the VibeTide level domain, including CRUD operations (create, edit, view), metadata management, tile reference, and gameplay integration. There are no obvious gaps; agents can handle the full lifecycle from design to playtesting seamlessly.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers