mcp-romm 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. mcp_romm-0.1.0/LICENSE +21 -0
  2. mcp_romm-0.1.0/PKG-INFO +147 -0
  3. mcp_romm-0.1.0/README.md +135 -0
  4. mcp_romm-0.1.0/mcp_romm.egg-info/PKG-INFO +147 -0
  5. mcp_romm-0.1.0/mcp_romm.egg-info/SOURCES.txt +10 -0
  6. mcp_romm-0.1.0/mcp_romm.egg-info/dependency_links.txt +1 -0
  7. mcp_romm-0.1.0/mcp_romm.egg-info/entry_points.txt +2 -0
  8. mcp_romm-0.1.0/mcp_romm.egg-info/requires.txt +2 -0
  9. mcp_romm-0.1.0/mcp_romm.egg-info/top_level.txt +1 -0
  10. mcp_romm-0.1.0/pyproject.toml +14 -0
  11. mcp_romm-0.1.0/server.py +1026 -0
  12. mcp_romm-0.1.0/setup.cfg +4 -0
mcp_romm-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 lodordev
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
mcp_romm-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,147 @@
1
+ Metadata-Version: 2.4
2
+ Name: mcp-romm
3
+ Version: 0.1.0
4
+ Summary: MCP server for RomM — browse and manage your retro game library with AI
5
+ License-Expression: MIT
6
+ Requires-Python: >=3.10
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Requires-Dist: fastmcp>=2.0.0
10
+ Requires-Dist: httpx>=0.27.0
11
+ Dynamic: license-file
12
+
13
+ # RomM MCP Server
14
+
15
+ An [MCP](https://modelcontextprotocol.io) server for [RomM](https://github.com/rommapp/romm) — the self-hosted retro game library manager. 19 read-only tools for browsing platforms, searching ROMs, viewing metadata, managing collections, tracking saves, and monitoring tasks through any MCP-compatible AI assistant.
16
+
17
+ ## Tools
18
+
19
+ | Tool | Description |
20
+ |------|-------------|
21
+ | `romm_status` | Check server configuration and reachability |
22
+ | `romm_stats` | Library-wide statistics (platforms, ROMs, saves, total size) |
23
+ | `romm_platforms` | List platforms with ROM counts and sizes |
24
+ | `romm_library_items` | Browse ROMs with filtering and pagination |
25
+ | `romm_recent` | Recently added or updated ROMs |
26
+ | `romm_get_item` | Full ROM detail — metadata, saves, user status |
27
+ | `romm_search` | Search ROMs by name |
28
+ | `romm_search_by_hash` | Identify a ROM by file hash (CRC, MD5, or SHA1) |
29
+ | `romm_filters` | Available filter values (genres, regions, languages, tags) |
30
+ | `romm_collections` | List user-curated collections |
31
+ | `romm_collection_detail` | List ROMs in a specific collection |
32
+ | `romm_smart_collections` | List auto-generated smart collections |
33
+ | `romm_saves` | List save files by ROM or platform |
34
+ | `romm_user_profile` | Browse by status (now playing, backlog, completed, etc.) |
35
+ | `romm_rom_notes` | View notes on a ROM |
36
+ | `romm_firmware` | List BIOS/firmware files per platform |
37
+ | `romm_devices` | List registered devices |
38
+ | `romm_tasks` | Check running/scheduled task status |
39
+ | `romm_scan_library` | Trigger a background library rescan |
40
+
41
+ ## Setup
42
+
43
+ ### Prerequisites
44
+
45
+ - Python 3.10+
46
+ - A running [RomM](https://github.com/rommapp/romm) instance (v4.0+)
47
+ - A RomM user account with admin role
48
+
49
+ ### Install
50
+
51
+ ```bash
52
+ pip install fastmcp httpx
53
+ ```
54
+
55
+ Or clone and install:
56
+
57
+ ```bash
58
+ git clone https://github.com/lodordev/mcp-romm.git
59
+ cd mcp-romm
60
+ pip install .
61
+ ```
62
+
63
+ ### Configure
64
+
65
+ Set environment variables:
66
+
67
+ | Variable | Required | Default | Description |
68
+ |----------|----------|---------|-------------|
69
+ | `ROMM_URL` | No | `http://localhost:3000` | Your RomM instance URL |
70
+ | `ROMM_USERNAME` | **Yes** | | RomM username |
71
+ | `ROMM_PASSWORD` | **Yes** | | RomM password |
72
+ | `ROMM_REQUEST_TIMEOUT` | No | `30` | Default request timeout (seconds) |
73
+ | `ROMM_REQUEST_TIMEOUT_LONG` | No | `60` | Timeout for slow endpoints |
74
+ | `ROMM_TLS_VERIFY` | No | `true` | Verify TLS certificates |
75
+
76
+ ### Add to Claude Code
77
+
78
+ Add to your `.mcp.json`:
79
+
80
+ ```json
81
+ {
82
+ "mcpServers": {
83
+ "romm": {
84
+ "command": "python",
85
+ "args": ["/path/to/mcp-romm/server.py"],
86
+ "env": {
87
+ "ROMM_URL": "http://your-romm-instance:3000",
88
+ "ROMM_USERNAME": "your-username",
89
+ "ROMM_PASSWORD": "your-password"
90
+ }
91
+ }
92
+ }
93
+ }
94
+ ```
95
+
96
+ ### Add to Claude Desktop
97
+
98
+ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
99
+
100
+ ```json
101
+ {
102
+ "mcpServers": {
103
+ "romm": {
104
+ "command": "python",
105
+ "args": ["/path/to/mcp-romm/server.py"],
106
+ "env": {
107
+ "ROMM_URL": "http://your-romm-instance:3000",
108
+ "ROMM_USERNAME": "your-username",
109
+ "ROMM_PASSWORD": "your-password"
110
+ }
111
+ }
112
+ }
113
+ }
114
+ ```
115
+
116
+ ## Examples
117
+
118
+ Once configured, you can ask your AI assistant things like:
119
+
120
+ - "What platforms do I have in RomM?"
121
+ - "Search for Zelda games"
122
+ - "Show me my backlog"
123
+ - "How many ROMs do I have total?"
124
+ - "What was recently added?"
125
+ - "Show me the saves for Super Metroid"
126
+ - "What's in my favorites?"
127
+ - "List my firmware files for PlayStation"
128
+ - "What tasks are running?"
129
+ - "What devices are registered?"
130
+
131
+ ## Security
132
+
133
+ - **Read-only.** All 19 tools are read-only. The only mutation is `romm_scan_library`, which triggers an idempotent library rescan.
134
+ - **No disk writes.** Credentials and tokens are held in memory only, never written to disk.
135
+ - **Scoped tokens.** OAuth2 tokens request only the scopes needed for read operations.
136
+ - **TLS by default.** Certificate verification is enabled by default (`ROMM_TLS_VERIFY=true`).
137
+ - **Auto-retry.** If a token expires mid-session, the server re-authenticates transparently.
138
+
139
+ ## Auth
140
+
141
+ The server uses OAuth2 password grant to authenticate with RomM. Tokens are scoped to the minimum permissions needed and automatically refreshed when they expire. If a request gets a 401, the server re-authenticates and retries once.
142
+
143
+ **Note:** Your RomM user must have the **admin** role for all tools to work. The user must also be **enabled** in the RomM admin panel.
144
+
145
+ ## License
146
+
147
+ MIT
mcp_romm-0.1.0/README.md ADDED
@@ -0,0 +1,135 @@
1
+ # RomM MCP Server
2
+
3
+ An [MCP](https://modelcontextprotocol.io) server for [RomM](https://github.com/rommapp/romm) — the self-hosted retro game library manager. 19 read-only tools for browsing platforms, searching ROMs, viewing metadata, managing collections, tracking saves, and monitoring tasks through any MCP-compatible AI assistant.
4
+
5
+ ## Tools
6
+
7
+ | Tool | Description |
8
+ |------|-------------|
9
+ | `romm_status` | Check server configuration and reachability |
10
+ | `romm_stats` | Library-wide statistics (platforms, ROMs, saves, total size) |
11
+ | `romm_platforms` | List platforms with ROM counts and sizes |
12
+ | `romm_library_items` | Browse ROMs with filtering and pagination |
13
+ | `romm_recent` | Recently added or updated ROMs |
14
+ | `romm_get_item` | Full ROM detail — metadata, saves, user status |
15
+ | `romm_search` | Search ROMs by name |
16
+ | `romm_search_by_hash` | Identify a ROM by file hash (CRC, MD5, or SHA1) |
17
+ | `romm_filters` | Available filter values (genres, regions, languages, tags) |
18
+ | `romm_collections` | List user-curated collections |
19
+ | `romm_collection_detail` | List ROMs in a specific collection |
20
+ | `romm_smart_collections` | List auto-generated smart collections |
21
+ | `romm_saves` | List save files by ROM or platform |
22
+ | `romm_user_profile` | Browse by status (now playing, backlog, completed, etc.) |
23
+ | `romm_rom_notes` | View notes on a ROM |
24
+ | `romm_firmware` | List BIOS/firmware files per platform |
25
+ | `romm_devices` | List registered devices |
26
+ | `romm_tasks` | Check running/scheduled task status |
27
+ | `romm_scan_library` | Trigger a background library rescan |
28
+
29
+ ## Setup
30
+
31
+ ### Prerequisites
32
+
33
+ - Python 3.10+
34
+ - A running [RomM](https://github.com/rommapp/romm) instance (v4.0+)
35
+ - A RomM user account with admin role
36
+
37
+ ### Install
38
+
39
+ ```bash
40
+ pip install fastmcp httpx
41
+ ```
42
+
43
+ Or clone and install:
44
+
45
+ ```bash
46
+ git clone https://github.com/lodordev/mcp-romm.git
47
+ cd mcp-romm
48
+ pip install .
49
+ ```
50
+
51
+ ### Configure
52
+
53
+ Set environment variables:
54
+
55
+ | Variable | Required | Default | Description |
56
+ |----------|----------|---------|-------------|
57
+ | `ROMM_URL` | No | `http://localhost:3000` | Your RomM instance URL |
58
+ | `ROMM_USERNAME` | **Yes** | | RomM username |
59
+ | `ROMM_PASSWORD` | **Yes** | | RomM password |
60
+ | `ROMM_REQUEST_TIMEOUT` | No | `30` | Default request timeout (seconds) |
61
+ | `ROMM_REQUEST_TIMEOUT_LONG` | No | `60` | Timeout for slow endpoints |
62
+ | `ROMM_TLS_VERIFY` | No | `true` | Verify TLS certificates |
63
+
64
+ ### Add to Claude Code
65
+
66
+ Add to your `.mcp.json`:
67
+
68
+ ```json
69
+ {
70
+ "mcpServers": {
71
+ "romm": {
72
+ "command": "python",
73
+ "args": ["/path/to/mcp-romm/server.py"],
74
+ "env": {
75
+ "ROMM_URL": "http://your-romm-instance:3000",
76
+ "ROMM_USERNAME": "your-username",
77
+ "ROMM_PASSWORD": "your-password"
78
+ }
79
+ }
80
+ }
81
+ }
82
+ ```
83
+
84
+ ### Add to Claude Desktop
85
+
86
+ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
87
+
88
+ ```json
89
+ {
90
+ "mcpServers": {
91
+ "romm": {
92
+ "command": "python",
93
+ "args": ["/path/to/mcp-romm/server.py"],
94
+ "env": {
95
+ "ROMM_URL": "http://your-romm-instance:3000",
96
+ "ROMM_USERNAME": "your-username",
97
+ "ROMM_PASSWORD": "your-password"
98
+ }
99
+ }
100
+ }
101
+ }
102
+ ```
103
+
104
+ ## Examples
105
+
106
+ Once configured, you can ask your AI assistant things like:
107
+
108
+ - "What platforms do I have in RomM?"
109
+ - "Search for Zelda games"
110
+ - "Show me my backlog"
111
+ - "How many ROMs do I have total?"
112
+ - "What was recently added?"
113
+ - "Show me the saves for Super Metroid"
114
+ - "What's in my favorites?"
115
+ - "List my firmware files for PlayStation"
116
+ - "What tasks are running?"
117
+ - "What devices are registered?"
118
+
119
+ ## Security
120
+
121
+ - **Read-only.** All 19 tools are read-only. The only mutation is `romm_scan_library`, which triggers an idempotent library rescan.
122
+ - **No disk writes.** Credentials and tokens are held in memory only, never written to disk.
123
+ - **Scoped tokens.** OAuth2 tokens request only the scopes needed for read operations.
124
+ - **TLS by default.** Certificate verification is enabled by default (`ROMM_TLS_VERIFY=true`).
125
+ - **Auto-retry.** If a token expires mid-session, the server re-authenticates transparently.
126
+
127
+ ## Auth
128
+
129
+ The server uses OAuth2 password grant to authenticate with RomM. Tokens are scoped to the minimum permissions needed and automatically refreshed when they expire. If a request gets a 401, the server re-authenticates and retries once.
130
+
131
+ **Note:** Your RomM user must have the **admin** role for all tools to work. The user must also be **enabled** in the RomM admin panel.
132
+
133
+ ## License
134
+
135
+ MIT
mcp_romm-0.1.0/mcp_romm.egg-info/PKG-INFO ADDED
@@ -0,0 +1,147 @@
1
+ Metadata-Version: 2.4
2
+ Name: mcp-romm
3
+ Version: 0.1.0
4
+ Summary: MCP server for RomM — browse and manage your retro game library with AI
5
+ License-Expression: MIT
6
+ Requires-Python: >=3.10
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Requires-Dist: fastmcp>=2.0.0
10
+ Requires-Dist: httpx>=0.27.0
11
+ Dynamic: license-file
12
+
13
+ # RomM MCP Server
14
+
15
+ An [MCP](https://modelcontextprotocol.io) server for [RomM](https://github.com/rommapp/romm) — the self-hosted retro game library manager. 19 read-only tools for browsing platforms, searching ROMs, viewing metadata, managing collections, tracking saves, and monitoring tasks through any MCP-compatible AI assistant.
16
+
17
+ ## Tools
18
+
19
+ | Tool | Description |
20
+ |------|-------------|
21
+ | `romm_status` | Check server configuration and reachability |
22
+ | `romm_stats` | Library-wide statistics (platforms, ROMs, saves, total size) |
23
+ | `romm_platforms` | List platforms with ROM counts and sizes |
24
+ | `romm_library_items` | Browse ROMs with filtering and pagination |
25
+ | `romm_recent` | Recently added or updated ROMs |
26
+ | `romm_get_item` | Full ROM detail — metadata, saves, user status |
27
+ | `romm_search` | Search ROMs by name |
28
+ | `romm_search_by_hash` | Identify a ROM by file hash (CRC, MD5, or SHA1) |
29
+ | `romm_filters` | Available filter values (genres, regions, languages, tags) |
30
+ | `romm_collections` | List user-curated collections |
31
+ | `romm_collection_detail` | List ROMs in a specific collection |
32
+ | `romm_smart_collections` | List auto-generated smart collections |
33
+ | `romm_saves` | List save files by ROM or platform |
34
+ | `romm_user_profile` | Browse by status (now playing, backlog, completed, etc.) |
35
+ | `romm_rom_notes` | View notes on a ROM |
36
+ | `romm_firmware` | List BIOS/firmware files per platform |
37
+ | `romm_devices` | List registered devices |
38
+ | `romm_tasks` | Check running/scheduled task status |
39
+ | `romm_scan_library` | Trigger a background library rescan |
40
+
41
+ ## Setup
42
+
43
+ ### Prerequisites
44
+
45
+ - Python 3.10+
46
+ - A running [RomM](https://github.com/rommapp/romm) instance (v4.0+)
47
+ - A RomM user account with admin role
48
+
49
+ ### Install
50
+
51
+ ```bash
52
+ pip install fastmcp httpx
53
+ ```
54
+
55
+ Or clone and install:
56
+
57
+ ```bash
58
+ git clone https://github.com/lodordev/mcp-romm.git
59
+ cd mcp-romm
60
+ pip install .
61
+ ```
62
+
63
+ ### Configure
64
+
65
+ Set environment variables:
66
+
67
+ | Variable | Required | Default | Description |
68
+ |----------|----------|---------|-------------|
69
+ | `ROMM_URL` | No | `http://localhost:3000` | Your RomM instance URL |
70
+ | `ROMM_USERNAME` | **Yes** | | RomM username |
71
+ | `ROMM_PASSWORD` | **Yes** | | RomM password |
72
+ | `ROMM_REQUEST_TIMEOUT` | No | `30` | Default request timeout (seconds) |
73
+ | `ROMM_REQUEST_TIMEOUT_LONG` | No | `60` | Timeout for slow endpoints |
74
+ | `ROMM_TLS_VERIFY` | No | `true` | Verify TLS certificates |
75
+
76
+ ### Add to Claude Code
77
+
78
+ Add to your `.mcp.json`:
79
+
80
+ ```json
81
+ {
82
+ "mcpServers": {
83
+ "romm": {
84
+ "command": "python",
85
+ "args": ["/path/to/mcp-romm/server.py"],
86
+ "env": {
87
+ "ROMM_URL": "http://your-romm-instance:3000",
88
+ "ROMM_USERNAME": "your-username",
89
+ "ROMM_PASSWORD": "your-password"
90
+ }
91
+ }
92
+ }
93
+ }
94
+ ```
95
+
96
+ ### Add to Claude Desktop
97
+
98
+ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
99
+
100
+ ```json
101
+ {
102
+ "mcpServers": {
103
+ "romm": {
104
+ "command": "python",
105
+ "args": ["/path/to/mcp-romm/server.py"],
106
+ "env": {
107
+ "ROMM_URL": "http://your-romm-instance:3000",
108
+ "ROMM_USERNAME": "your-username",
109
+ "ROMM_PASSWORD": "your-password"
110
+ }
111
+ }
112
+ }
113
+ }
114
+ ```
115
+
116
+ ## Examples
117
+
118
+ Once configured, you can ask your AI assistant things like:
119
+
120
+ - "What platforms do I have in RomM?"
121
+ - "Search for Zelda games"
122
+ - "Show me my backlog"
123
+ - "How many ROMs do I have total?"
124
+ - "What was recently added?"
125
+ - "Show me the saves for Super Metroid"
126
+ - "What's in my favorites?"
127
+ - "List my firmware files for PlayStation"
128
+ - "What tasks are running?"
129
+ - "What devices are registered?"
130
+
131
+ ## Security
132
+
133
+ - **Read-only.** All 19 tools are read-only. The only mutation is `romm_scan_library`, which triggers an idempotent library rescan.
134
+ - **No disk writes.** Credentials and tokens are held in memory only, never written to disk.
135
+ - **Scoped tokens.** OAuth2 tokens request only the scopes needed for read operations.
136
+ - **TLS by default.** Certificate verification is enabled by default (`ROMM_TLS_VERIFY=true`).
137
+ - **Auto-retry.** If a token expires mid-session, the server re-authenticates transparently.
138
+
139
+ ## Auth
140
+
141
+ The server uses OAuth2 password grant to authenticate with RomM. Tokens are scoped to the minimum permissions needed and automatically refreshed when they expire. If a request gets a 401, the server re-authenticates and retries once.
142
+
143
+ **Note:** Your RomM user must have the **admin** role for all tools to work. The user must also be **enabled** in the RomM admin panel.
144
+
145
+ ## License
146
+
147
+ MIT
mcp_romm-0.1.0/mcp_romm.egg-info/SOURCES.txt ADDED
@@ -0,0 +1,10 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ server.py
5
+ mcp_romm.egg-info/PKG-INFO
6
+ mcp_romm.egg-info/SOURCES.txt
7
+ mcp_romm.egg-info/dependency_links.txt
8
+ mcp_romm.egg-info/entry_points.txt
9
+ mcp_romm.egg-info/requires.txt
10
+ mcp_romm.egg-info/top_level.txt
mcp_romm-0.1.0/mcp_romm.egg-info/entry_points.txt ADDED
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ romm-mcp = server:mcp.run
mcp_romm-0.1.0/mcp_romm.egg-info/requires.txt ADDED
@@ -0,0 +1,2 @@
1
+ fastmcp>=2.0.0
2
+ httpx>=0.27.0
mcp_romm-0.1.0/mcp_romm.egg-info/top_level.txt ADDED
@@ -0,0 +1 @@
1
+ server
mcp_romm-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,14 @@
1
+ [project]
2
+ name = "mcp-romm"
3
+ version = "0.1.0"
4
+ description = "MCP server for RomM — browse and manage your retro game library with AI"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ requires-python = ">=3.10"
8
+ dependencies = [
9
+ "fastmcp>=2.0.0",
10
+ "httpx>=0.27.0",
11
+ ]
12
+
13
+ [project.scripts]
14
+ romm-mcp = "server:mcp.run"