# Gearcoleco MCP Server

> Gearcoleco MCP Server is an open-source MCP server for developer tools. ColecoVision and Coleco ADAM emulator with an embedded MCP server for AI debugging. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** Windows, macOS, Linux, CLI
- **Repository:** https://github.com/drhelius/gearcoleco
- **MCP Registry name:** io.github.drhelius/gearcoleco
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [games and play](https://ai-powered.com/categories/games-and-play)
- **Listing updated:** 2026-11-18

## About

Gearcoleco emulates the ColecoVision console and the Coleco ADAM computer in C++, and its MCP server lets an AI client such as Claude Code or Codex drive the emulator. The README says the tools cover execution control, memory inspection, hardware status and rewind, though it does not list individual tool names.

Emulation includes the Z80, TMS9918A video chip, SN76489 sound chip and AY-3-8910 for the Super Game Module, plus MegaCart ROMs and optional F18A v1.9. For the ADAM it supports cartridge and computer boot modes, keyboard, ADAMnet, printer, Digital Data Pack and floppy images, and a per-game keyboard mapper. Super Action Controller, Wheel and Roller controllers with mouse-driven spinners are supported.

The built-in debugger has a disassembler, breakpoints, memory editor, trace logger and a VRAM viewer for registers, tiles, sprites and backgrounds. Firmware is not included: you supply the ColecoVision BIOS, and for the ADAM the EOS and SmartWriter ROMs. It runs on Windows, macOS, Linux, BSD and RetroArch, and the registry offers per-platform MCPB bundles.

## Features

- **Embedded MCP server:** Lets AI clients control execution and inspect memory and hardware state.
- **ColecoVision and ADAM:** Emulates both the console and the ADAM computer with disk and data pack support.
- **Accurate hardware:** Models the Z80, TMS9918A, SN76489 and AY-3-8910 chips.
- **Debugger:** Disassembler, breakpoints, trace logger, memory editor and VRAM viewer.
- **Controller support:** Handles Super Action, Wheel and Roller controllers with spinners.
- **Save states and rewind:** Includes previews, rewind and run-ahead.

## Good for

- Debug ColecoVision homebrew with an AI assistant
- Inspect VRAM tiles and sprites while a game runs
- Run ADAM software from disk and data pack images
- Play ColecoVision cartridges with shaders and rewind
- Trace Z80 execution to find a bug

## Install

### Claude Code (Terminal)

```sh
claude mcp add gearcoleco -- npx -y https://github.com/drhelius/gearcoleco/releases/download/1.8.0/Gearcoleco-1.8.0-mcpb-macos-arm64.mcpb
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "gearcoleco": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/drhelius/gearcoleco/releases/download/1.8.0/Gearcoleco-1.8.0-mcpb-macos-arm64.mcpb"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "gearcoleco": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/drhelius/gearcoleco/releases/download/1.8.0/Gearcoleco-1.8.0-mcpb-macos-arm64.mcpb"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "gearcoleco": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/drhelius/gearcoleco/releases/download/1.8.0/Gearcoleco-1.8.0-mcpb-macos-arm64.mcpb"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "gearcoleco": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/drhelius/gearcoleco/releases/download/1.8.0/Gearcoleco-1.8.0-mcpb-macos-arm64.mcpb"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "gearcoleco": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/drhelius/gearcoleco/releases/download/1.8.0/Gearcoleco-1.8.0-mcpb-macos-arm64.mcpb"
      ]
    }
  }
}
```

## FAQ

### Is a BIOS included?

No. You select your own ColecoVision BIOS, and the ADAM needs EOS and SmartWriter ROMs as well.

### Which platforms does it run on?

Windows, macOS, Linux, BSD and RetroArch.

### What ADAM media formats work?

256 KiB .ddp, 160/320 KiB .dsk, ZIP archives of one image, and .m3u playlists.

### How is it licensed or funded?

It is an open-source project supported by sponsors.

### Is Gearcoleco MCP Server free?

Yes. Gearcoleco MCP Server is open source, so you can use and self-host it for free.

### How do I add Gearcoleco MCP Server to Claude Code?

Run this command in your terminal: claude mcp add gearcoleco -- npx -y https://github.com/drhelius/gearcoleco/releases/download/1.8.0/Gearcoleco-1.8.0-mcpb-macos-arm64.mcpb

### What are the best alternatives to Gearcoleco MCP Server?

The closest alternatives to Gearcoleco MCP Server are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/gearcoleco-mcp-server
