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. It also works with other VPS hosts whose control panel runs VirtFusion, such as GreenCloud. See Other VirtFusion panels.

  • 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.2.0

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.gomami]
command = "uvx"
args = ["gomami-mcp@0.2.0"]
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.2.0"],
      "env": { "GOMAMI_MCP_ACCESS": "read" }
    }
  }
}

VS Code

Add this to .vscode/mcp.json:

{
  "servers": {
    "gomami": {
      "type": "stdio",
      "command": "uvx",
      "args": ["gomami-mcp@0.2.0"],
      "env": { "GOMAMI_MCP_ACCESS": "read" }
    }
  }
}

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "gomami": {
      "command": "uvx",
      "args": ["gomami-mcp@0.2.0"],
      "env": { "GOMAMI_MCP_ACCESS": "read" }
    }
  }
}

Other agents

Configure a local stdio server with this command:

uvx gomami-mcp@0.2.0

For DeepSeek Harness, use this command with its @deepseek-ai/dsh-mcp-client plugin.

Other VirtFusion panels

GoMami's panel is VirtFusion. Other hosts that use VirtFusion expose the same customer API, so you can point this server at their panel instead. Look for an API page in your panel, such as /account/api.

  1. Save that panel's token. Each panel gets its own file, named after the panel's host. For example, for GreenCloud (cp.green.cloud):

    (umask 077; mkdir -p ~/.config/gomami-mcp; IFS= read -rs t; printf '%s\n' "$t" > ~/.config/gomami-mcp/token-cp.green.cloud; unset t)
    
  2. Add a second server entry with GOMAMI_API_BASE set to the panel's API URL. For Claude Code:

    claude mcp add greencloud --scope user -e GOMAMI_API_BASE=https://cp.green.cloud/api -- uvx gomami-mcp@0.2.0
    

GreenCloud has been tested with the read-only tools. Other panels have not been tested, and a host may turn off parts of the API.

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_BASE https://cp.gomami.io/api API URL of a VirtFusion panel. Only https:// is accepted. If the value is invalid, every request is refused instead of falling back to GoMami.
GOMAMI_TOKEN_FILE see note Token file. Defaults to ~/.config/gomami-mcp/token for GoMami and ~/.config/gomami-mcp/token-<host> for other panels, so a token is never sent to the wrong host.
GOMAMI_API_TOKEN empty Token value. Takes priority over the token file. If you use more than one panel, prefer token files, because this value is sent to whichever panel GOMAMI_API_BASE names.

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

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.2.0
File Size Uploaded Provenance Actions
gomami_mcp-0.2.0.tar.gz 18.7 kB With provenance Details for gomami_mcp-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gomami-mcp 0.2.0
File Interpreter ABI Platform Actions
gomami_mcp-0.2.0-py3-none-any.whl Python 3 none any Details for gomami_mcp-0.2.0-py3-none-any.whl

Total release size: 33.5 kB

Release files / gomami_mcp-0.2.0.tar.gz

Download URL gomami_mcp-0.2.0.tar.gz
Size 18.7 kB
Tags Source
SHA-256 checksum
How to use checksums
bfdcea9fa794231330ab9344bce3349f552f0a8f4c2fd1c5432ad53e67eac447
BLAKE2b-256 checksum
How to use checksums
f08fd0683740e15f80fae3edd3836c17259caee55000c109b74f7b11fd1b99b3
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.2.0-py3-none-any.whl

Download URL gomami_mcp-0.2.0-py3-none-any.whl
Size 14.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
696372ff45a83c7dd3e16a7645c98a05b4a82af1af2a7d42c56c8f6a478b7769
BLAKE2b-256 checksum
How to use checksums
7f6f7df5fc85e863837c0ba966ea2d7bcb82243194cd66f3ed0f5066a4571fd8
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.2.0

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