This MCP server provides a set of PICO-8 cart analysis and manipulation tools integrated into the MCP framework. It exposes capabilities for token counting, code analysis, cart validation, code pattern searching, cart comparison, and functionality to read, minify, and list carts. It also includes documentation tooling to fetch and store PICO-8 documentation resources that can be referenced during development. You can use these tools by invoking Claude with questions like counting tokens in a cart, analyzing a cart’s structure, validating token limits, or comparing two cart versions. The server wires these commands to functions such as count_tokens, analyze_cart, validate_cart, search_code, compare_carts, read_cart, minify_cart, list_carts, and add_documentation, with saved resources accessible via pico8:// docs paths.

Prerequisites:

• Python 3.8+ installed on your system
• uv package manager installed (see https://github.com/astral-sh/uv)

Setup steps:

1. Clone the repository: git clone https://github.com/YOUR_USERNAME/pico8-mcp-server.git cd pico8-mcp-server

2. Initialize the shrinko8 submodule: git submodule update --init --recursive

3. Install dependencies and set up uv: uv sync

4. Run the server locally:

   Start the MCP server using uv

   uv run server.py

Optional Claude configuration (for Claude Code / Claude Desktop):

• Create a .mcp.json in your project root with the following: { "mcpServers": { "pico8": { "command": "uv", "args": ["run", "/path/to/your/pico8-mcp-server/server.py"] } } }
• Or add to Claude Desktop config accordingly, replacing the path with your local repo path.

Tips and notes:

• Ensure you have correctly initialized the shrinko8 submodule, as the MCP server relies on it for cart tooling.
• The uv-based setup assumes you’re running from a local clone; adjust the server path in your mcp.json accordingly.
• Documentation resources saved via add_documentation can be accessed through pico8://docs endpoints; use the fetch feature to populate API references as needed.
• When configuring Claude, ensure the directory or path specified in the args points to your local pico8-mcp-server directory to allow cart discovery and processing.
• If you encounter token or linting errors during validate_cart, confirm that your cart format is valid and that the token limits align with the PICO-8 API constraints used by shrinko8.