home / mcp / vibetide mcp server

VibeTide MCP Server

MCP Server to build and play VibeTide

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "banjtheman-vibe_tide_mcp": {
      "command": "python",
      "args": [
        "/path/to/vibe_tide_mcp_server.py"
      ]
    }
  }
}

You can run the VibeTide MCP Server to create, edit, visualize, and play 2D platformer levels using the MCP protocol. This server exposes tools for level manipulation, AI-assisted creation, and easy sharing, so you can build and test levels with a consistent, programmable interface.

How to use

To work with an MCP client, run the server in stdio mode and connect your client to the running process. You can use a local Python-based server or the UVX runner to launch the MCP server. Once the server is running, you can create, edit, view, and play levels through the MCP client by invoking the provided tools. The client sends requests to the server, which responds with encoded level data, visualizations, or playable URLs.

How to install

Prerequisites you need before starting:
- Python installed on your machine
- Optional: uvx installed for direct running without local installation
- Optional: Node.js and npm if you prefer using a package-based workflow via Smithery or similar tooling

# Prerequisites (example introductions)
python --version
uvx --version 2>/dev/null || echo "UVX not installed"
 node -v 2>/dev/null || echo "Node.js not installed"

Local Python server (recommended for quickstart)

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

Using UVX to run directly

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

Additional setup notes

After you configure an MCP client with one or more servers, start the client. The client will launch the MCP server process and maintain a connection for sending requests such as creating levels, editing tiles, viewing ASCII/PNG visualizations, decoding from URLs, and obtaining play URLs.

Configuration details

Configure your MCP client to point to the local Python server or the UVX-run server using the JSON examples above. If you switch between local execution and UVX, ensure the command and arguments are aligned with the chosen method.

Security and access

Keep local access restricted to trusted clients when running servers on shared machines. Do not expose the running MCP server endpoints to untrusted networks without proper authentication or access controls.

Troubleshooting

If you encounter connection issues, verify that the MCP server process is running, the command and arguments are correct, and the client is configured with the exact server name and path. Check for Python or UVX runtime errors in the terminal where you started the server.

Available tools

create_level

Create new levels with AI assistance, specifying level name, description, dimensions, and optional configuration for enemies and items.

edit_entire_level

Replace all tiles in an existing level with a new tile matrix.

edit_level_tile

Edit a single tile by specifying row, column, and the new tile type.

edit_level_row

Edit an entire row of tiles in a level.

edit_level_metadata

Update level properties such as name, spawn rates, difficulty, and other metadata.

decode_level_from_url

Decode a level from a sharing URL into the server's internal representation.

view_level

Generate an ASCII visualization of a level for quick review.

view_level_image

Create a PNG visualization of a level for sharing or presentation.

play_level

Provide a URL to play the level in the web-based level player.

get_tile_reference

Provide a reference guide for all tile types used in levels.