Identify and Match your ROMs at blazingly fast speed

Playmatch is an open-source service to match, identify and verify your ROMs while also providing & caching metadata for them.

The public API is available at playmatch.retrorealm.dev

Features

Supported

• Supports No-Intro, Redump (Public and Private) and certain Community Dat files
• Automatically daily downloads and updates dat files
• Hash dat files to skip daily import if nothing changed
• Support for IGDB as metadata provider
• Full IGDB entity endpoints exposed through a caching proxy
• Support for SteamGridDB as metadata provider
• Support for ScreenScraper as metadata provider
• Support for MobyGames as metadata provider
• Support for LaunchBox as metadata provider (bulk metadata import, opt-in via LAUNCHBOX_ENABLED)
• Support for OpenVGDB as metadata provider (offline SQLite hash matching, opt-in via OPENVGDB_ENABLED)
• Support for EmuReady as metadata provider (id-mapping only, opt-in via EMUREADY_ENABLED)
• Support for RetroAchievements as metadata provider (bulk import via API, MD5 hash matching plus name fallback, opt-in via RETROACHIEVEMENTS_USERNAME + RETROACHIEVEMENTS_API_KEY)
• Support for TheGamesDB as metadata provider (catalogue seeded via migration, capped API search-on-miss with Redis-backed quota, opt-in via TGDB_ENABLED plus optional TGDB_API_KEY)
• Support for Hasheous as metadata provider (hash-based matching against public signature DATs including No-Intro, Redump, TOSEC, MAMEArcade and RetroAchievements, opt-in via HASHEOUS_ENABLED)

Planned

• Support for more dat files sources (TOSEC, MAME, GoodTools, etc)
• Support for more metadata providers
• Support bios and other non-game files, which you can also hash and verify this way

Getting Started

Prerequisites

1. Rust 1.95+ from here
2. PostgreSQL 18+ from here
3. A Redis-compatible server such as Redis, Valkey, or DragonflyDB

Development

1. Clone the repository
2. Rename .env.example to .env and fill in the required environment variables
3. Run cargo run --package playmatch --bin playmatch to start the server

MCP server

Playmatch ships a Model Context Protocol server so AI agents can identify ROMs and browse the catalogue with the same data the public API serves. It is mounted on the main API listener and speaks MCP over Streamable HTTP at /mcp (so the endpoint is http://<host>:<PORT>/mcp). It shares the public API per-IP rate limit.

It is controlled by these environment variables:

• MCP_ENABLED - set to false to disable the server. Defaults to true.
• MCP_PUBLIC_URL - the public origin of the deployment (for example https://playmatch.retrorealm.dev). Used to advertise the endpoint in the discovery document. Leave empty to omit the remote entry.

The server publishes an MCP Server Card at /.well-known/mcp-server-card (and the same document at /.well-known/mcp.json). A client that already knows the host can read the card to learn the endpoint and metadata without connecting. This is a self-hosted card, not a registry listing, so it does not by itself make registries aware of the server.

The MCP session manager is kept in-process, so the deployment must run as a single instance. This is the same constraint as the in-process cron and import jobs.

The server exposes these tools:

• playmatch_identify_rom_by_hash - identify a ROM and return its game id and external metadata provider ids.
• playmatch_identify_rom_with_relations - identify a ROM and return the game with its platform, company, signature group, dat file and files.
• playmatch_get_game - fetch a single game and its external metadata by id.
• playmatch_get_game_with_relations - fetch a game with its full relations by id.
• playmatch_get_game_file_history - list the dat file imports a game file was seen in by game file id.
• playmatch_list_companies / playmatch_get_company - browse or fetch companies.
• playmatch_list_platforms / playmatch_get_platform - browse or fetch platforms.
• playmatch_list_signature_groups / playmatch_get_signature_group - browse or fetch signature groups (dat publishers such as No-Intro and Redump).

Deployment

Docker images are available Here

Built With

• Rust - The programming language used
• tokio - The async runtime used
• reqwest - HTTP client
• serde - Serialization/Deserialization
• actix-web - The web framework used
• SeaORM - The Database ORM used
• Redis / Valkey / DragonflyDB - Used for caching and rate limiting

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• DevYukine - Initial work - DevYukine

See also the list of contributors who participated in this project.

License

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

Acknowledgments

• hasheous - Another Project for the same goal