Skip to main content

GoMami MCP

Test Release Python 3.10+ License: MIT

简体中文

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_account and list_servers have 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 mode 600.
  • 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_iso needs to eject an ISO.
  • The API reference describes GET /server/{id}/vnc as a toggle, which looks like a typo. It is placed in the operate tier 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

MIT

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)

Source distribution for gomami-mcp 0.1.1
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)

Table of built distributions (wheels) for gomami-mcp 0.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page