Pico8

A local MCP server for analyzing, reading, minifying, and documenting PICO-8 carts via MCP clients.

python

5

GitHub Stars

python

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "ebonura-pico8-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "/Users/ebonura/Desktop/repos/pico8-mcp-server/server.py"
      ]
    }
  }
}

This MCP server helps you work with PICO-8 game carts by analyzing, transforming, and documenting carts through a local runtime. It enables token counting, code analysis, cart validation, and convenient documentation tooling, all orchestrated via MCP clients to streamline development workflows.

How to use

You connect an MCP client to the Pico8 MCP Server to run analyses, read cart data, and manage documentation resources. Typical workflows include counting tokens in a cart, inspecting functions and globals, validating carts against token limits, and minifying carts to reduce token usage. You can also list carts in a directory, search across carts for specific patterns, and compare different cart versions to see diffs. When you add or fetch documentation, the server makes PICO-8 API references available as MCP resources for quick reference during coding.

How to install

Prerequisites: Python 3.8+ and the uv package manager.

Step 1. Prepare your environment.

Step 2. Install and set up.

Step 3. Run the server using one of the provided MCP configurations.

Additional configuration notes

The server supports local runtime usage through stdio configurations. You can start the server via the uv command with the server script path. Two common guidance examples are shown below as the runtime commands you can use in your MCP client.

{
  "mcpServers": [
    {
      "name": "pico8",
      "type": "stdio",
      "command": "uv",
      "args": ["run", "/Users/ebonura/Desktop/repos/pico8-mcp-server/server.py"]
    },
    {
      "name": "pico8_dir",
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/Users/ebonura/Desktop/repos/pico8-mcp-server", "run", "server.py"]
    }
  ]
}

Available tools

count_tokens

Count tokens, characters, and compressed size of carts or code snippets.

analyze_cart

List functions, globals, and code metrics within a cart to understand structure and complexity.

validate_cart

Validate a cart against token limits and linting rules to ensure it meets constraints.

search_code

Search for specific code patterns or strings across a collection of carts.

compare_carts

Compare two cart versions and show differences in code and metadata.

read_cart

Read cart sections such as code, gfx, map, sfx, and music.

minify_cart

Minify carts to reduce token usage while preserving functionality.

list_carts

List all carts in a directory along with metadata for quick reference.

add_documentation

Fetch and save PICO-8 documentation from URLs for offline reference.