GoMami MCP
Manage your GoMami servers from any AI agent that supports the Model Context Protocol, including Claude Code, Codex, Cursor and VS Code.
- Read-only by default. Changing a server has to be turned on explicitly.
- Runs on your computer. There is nothing to host, and your token goes only to GoMami.
- No third-party Python dependencies. It covers all 29 operations in the GoMami API reference.
Not affiliated with GoMami. This is an independent community project.
Alpha.
verify_connection,get_accountandlist_servershave been tested against the live API. All other tools, including every tool that changes a server, have only been tested against a local mock. Try them on a disposable server first.
What you can ask
- "List my GoMami servers and show their IP addresses."
- "When does this server's current traffic period end?"
- "Show the recent tasks for this server and tell me if any failed."
- "Which OS templates can I rebuild this server with?"
Supported agents
Any agent that can start a local MCP server over stdio should work.
| Agent | Status |
|---|---|
| Claude Code | Tested with the live API |
| Official MCP Python SDK | Protocol tested |
| Codex | Should work, not tested yet |
| Cursor | Should work, not tested yet |
| VS Code | Should work, not tested yet |
| Claude Desktop | Should work, not tested yet |
| DeepSeek Harness | Should work through its MCP client plugin, not tested yet |
| Web-only agents that need a remote HTTP server | Not supported |
If you try it with another agent, please share the result in Discussions.
Quick start
You need macOS or Linux, Python 3.10 or newer, uv and a GoMami API token.
1. Create a token
Sign in at gomami.io and open Create API Token. The token has full account access and is shown only once.
2. Save the token
Run this command, paste the token (nothing is displayed), then press Enter:
(umask 077; mkdir -p ~/.config/gomami-mcp; IFS= read -rs t; printf '%s\n' "$t" > ~/.config/gomami-mcp/token; unset t)
3. Add the server to your agent
Use one of the configurations below, then start a new session.
4. Check the connection
Ask your agent to run verify_connection.
Agent configuration
Desktop apps may not find uvx on their PATH. If the server fails to start, replace uvx with the full path printed by command -v uvx.
Claude Code
claude mcp add gomami --scope user -- uvx gomami-mcp@0.1.1
Codex
Add this to ~/.codex/config.toml:
[mcp_servers.gomami]
command = "uvx"
args = ["gomami-mcp@0.1.1"]
env = { GOMAMI_MCP_ACCESS = "read" }
startup_timeout_sec = 60
Cursor
Add this to ~/.cursor/mcp.json:
{
"mcpServers": {
"gomami": {
"type": "stdio",
"command": "uvx",
"args": ["gomami-mcp@0.1.1"],
"env": { "GOMAMI_MCP_ACCESS": "read" }
}
}
}
VS Code
Add this to .vscode/mcp.json:
{
"servers": {
"gomami": {
"type": "stdio",
"command": "uvx",
"args": ["gomami-mcp@0.1.1"],
"env": { "GOMAMI_MCP_ACCESS": "read" }
}
}
}
Claude Desktop
Add this to claude_desktop_config.json:
{
"mcpServers": {
"gomami": {
"command": "uvx",
"args": ["gomami-mcp@0.1.1"],
"env": { "GOMAMI_MCP_ACCESS": "read" }
}
}
}
Other agents
Configure a local stdio server with this command:
uvx gomami-mcp@0.1.1
For DeepSeek Harness, use this command with its @deepseek-ai/dsh-mcp-client plugin.
Settings
| Environment variable | Default | Purpose |
|---|---|---|
GOMAMI_MCP_ACCESS |
read |
Access tier: read, operate or full. Unknown values fall back to read. |
GOMAMI_MCP_PROTECTED_SERVERS |
empty | Comma-separated server IDs that can be read but not changed. |
GOMAMI_API_TOKEN |
empty | Token value. Takes priority over ~/.config/gomami-mcp/token. |
Tools
| Tier | Tools |
|---|---|
read |
verify_connection, get_account, list_ssh_keys, list_servers, get_server, list_os_templates, list_swap_options, list_isos, list_tasks, get_task, list_resource_packs, get_resource_pack |
operate |
All of the above, plus get_vnc_status, boot_server, restart_server, shutdown_server, power_off_server, rename_server |
full |
All of the above, plus rebuild_server, reset_server_password, toggle_rescue, toggle_vnc, set_iso, set_boot_order, update_server_settings, add_ssh_key, delete_ssh_key, create_resource_pack_server, delete_resource_pack_server |
Safety
- Protect production servers. Add them to
GOMAMI_MCP_PROTECTED_SERVERS. The MCP server enforces this list in every agent. - Do not rely on approval prompts alone. Whether an agent asks before running a tool depends on that agent and its settings.
- Confirmation text prevents mistakes, not decisions. Tools that change a server need text such as
REBUILD <server-id>, but a model can fill it in by itself. - Secrets stay out of the chat. VNC credentials are hidden, and reset passwords are saved under
~/.config/gomami-mcp/secrets/with mode600. - Write requests are never retried automatically.
See SECURITY.md for details and limits.
Known limitations
- Windows is not supported.
- The API reference does not say what value
set_isoneeds to eject an ISO. - The API reference describes
GET /server/{id}/vncas a toggle, which looks like a typo. It is placed in theoperatetier to be safe. - The API is behind Cloudflare. Blocked requests are reported clearly, and this project does not try to work around them.
Development
python3 -m unittest discover -s tests -v
Tests use a local mock and never contact GoMami.
License
Metadata
Release files for gomami-mcp 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gomami_mcp-0.1.1.tar.gz | 16.9 kB | With provenance | Details for gomami_mcp-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gomami_mcp-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for gomami_mcp-0.1.1-py3-none-any.whl |
Total release size: 30.6 kB
Release files / gomami_mcp-0.1.1.tar.gz
| Download URL | gomami_mcp-0.1.1.tar.gz |
|---|---|
| Size | 16.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7f07db9f65256f742b484a6c55157ddc22c232ae282b0a29805d8682f32c9bc4
|
|
BLAKE2b-256 checksum How to use checksums |
265c8bd0f62742c2f09ec66005f801464f773cb67cbf7d39283ab0b8bec52d9d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / gomami_mcp-0.1.1-py3-none-any.whl
| Download URL | gomami_mcp-0.1.1-py3-none-any.whl |
|---|---|
| Size | 13.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a52d666070851ee0761d84133826827a6c978c314d6a1257d17b2655a5fdab41
|
|
BLAKE2b-256 checksum How to use checksums |
068189976c11a546c4dc6a4de8caf9f8d7cdce6b818d63154bfc24069ae5744c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for gomami-mcp 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for gomami_mcp-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.