Gemini CLI + xCloud
Manage Your Hosting from Gemini CLI with xCloud
Gemini CLI is Google's command-line AI agent. Connected to xCloud through the MCP server, it deploys repositories, takes backups, updates WordPress, renews SSL and diagnoses failures from the terminal you already work in.
- One command: gemini mcp add
- OAuth discovered automatically
- Free with every xCloud account
YouIs SSL healthy on shop.example.com? Renew it if it is close to expiring.
sites_sslread-only
AgentThe certificate expires in nine days. I can renew it now. Go ahead?
YouYes.
sites_ssl_renewneeds approval
AgentRenewed. The site answers 200 over https with the new certificate.
. Keep a human in the loop: xCloud stops and asks before anything that creates, deploys, updates, reboots, deletes or buys.
Setup
How Do I Connect Gemini CLI to xCloud?
Point Gemini CLI at the xCloud MCP server, approve access in your browser, then ask. The whole thing takes a couple of minutes.
Add the xCloud MCP server
Run this in your terminal, then start gemini. The --scope user flag writes the server to ~/.gemini/settings.json so it is available in every project; without it, gemini mcp add writes to the current project's .gemini/settings.json and refuses to run from your home directory. The first time it calls xCloud it finds the OAuth endpoints, opens your browser on the xCloud approval screen and asks you to tick the teams and choose Read-only or Full access.
gemini mcp add --scope user --transport http xcloud https://app.xcloud.host/mcpOr edit settings.json
Add this to ~/.gemini/settings.json for every project, or to .gemini/settings.json in one project. This is the entry gemini mcp add writes: url plus type set to http. The older httpUrl key still works, but a url without a type is treated as an SSE server and will not connect. If the browser sign-in does not start, type /mcp auth xcloud inside Gemini CLI.
{ "mcpServers": { "xcloud": { "url": "https://app.xcloud.host/mcp", "type": "http" } } }No browser? Use an API key
For a headless machine, create a token with the mcp:invoke scope plus the read abilities for the areas it will use (read:servers and read:sites, with read:billing and read:addons for billing and add-on tools) and the matching write: abilities if it should change things in Settings, Developers, API Tokens and send it in the headers field. Keep the token out of version control, and keep the quotes: xCloud tokens contain a pipe character.
{ "mcpServers": { "xcloud": { "url": "https://app.xcloud.host/mcp", "type": "http", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }Check it worked
Gemini CLI detects the 401 from xCloud and runs the OAuth flow in your browser, so there is no token to paste into settings.json; Gemini CLI keeps the OAuth tokens it receives in its own credential store. A headless machine sends an API key with the mcp:invoke scope and the abilities it needs in the headers field.
Who am I on xCloud?
Three surfaces
Which Way Should I Connect Gemini CLI to xCloud?
The MCP server exposes one tool per customer-facing xCloud operation and leaves out eleven internal ones that only the Public API carries; the skills add workflow know-how on top of an MCP connection and, on their own, only read access. All three are free with every account and differ in what you set up and what holds the credentials.
| xCloud MCP server | xCloud Agent Skills | Public API | |
|---|---|---|---|
| Terminal needed | No (recommended for Gemini CLI) | Yes for the plugin or ClawHub install | Yes |
| Authentication | OAuth sign-in, or an API key with mcp:invoke plus read or write abilities (recommended for Gemini CLI) | The MCP connection, or a read-scoped API token | API token with scoped abilities |
| What it adds | One tool per customer-facing xCloud operation (188 today) (recommended for Gemini CLI) | Workflow know-how: routing, dry run, confirm, poll, diagnose | Raw REST for your own code |
| Changes to your infrastructure | Yes, after confirmation (recommended for Gemini CLI) | Only through a connected MCP tool, after confirmation | Yes, with write scopes |
| Best for | Most people; every MCP client (recommended for Gemini CLI) | Agents that run shell commands and read skills | CI jobs, dashboards and long-running loops |
Background
What Is Gemini CLI?
Gemini CLI is Google's command-line AI agent. It runs in your terminal, reads the files in your project, runs commands and works through multi-step tasks, asking for confirmation before it uses a tool that changes something.
It is a Model Context Protocol client. You register servers with gemini mcp add or in the mcpServers section of settings.json, and Gemini CLI discovers each server's tools and names them mcp_ followed by the server name and the tool name, so tools from different servers never collide.
xCloud's MCP server is a remote server of that kind. Once it is registered, Gemini CLI gets one tool per customer-facing xCloud operation, and a deploy, a backup or an SSL renewal becomes a sentence in the terminal instead of a trip to the dashboard.
Why Gemini CLI with xCloud?
One command, no config file
gemini mcp add writes the settings entry for you, and OAuth is found automatically when xCloud answers with a 401. There is no client ID to create and no token to paste.
User or project scope
Put the entry in ~/.gemini/settings.json to use xCloud everywhere, or in a project's .gemini/settings.json to keep it with that repository.
Confirmations stay on
Gemini CLI asks before it runs a tool, and xCloud adds its own confirmation rule for anything that creates, deploys, updates, reboots, deletes or buys. Two checks sit between a request and a change.
Guides
What Can Gemini CLI Do on xCloud?
One guide per hosting job, each with the Gemini CLI setup, the xCloud tools involved, a settings reference, example prompts and the limits that apply.
- Deploy from Git with Gemini CLITurn a GitHub, GitLab or Bitbucket repository into a live site on a server you already have.
- Run Docker apps with Gemini CLIRun a Dockerfile or Docker Compose app on a Docker server, keep it backed up and recover it when a deploy fails.
- Install one-click apps with Gemini CLIPick an app from the xCloud catalogue, check it fits your server, install it and get the login details.
- Manage WordPress with Gemini CLIKeep WordPress sites updated, scanned and healthy, and create new ones, by asking in plain words.
- Back up and stage sites with Gemini CLICheck that your sites are backed up, take a backup before a risky change, and open a staging copy to test it on.
- Manage SSL and domains with Gemini CLICheck a site's certificate and DNS, install or renew HTTPS, and see which domains point at it.
- Manage servers with Gemini CLISee how your servers are doing, change services and runtimes, tighten security and reboot with proof it worked.
- Troubleshoot a broken site with Gemini CLIFind out why a site returns a 500, 502 or 503, shows a critical error or has stopped answering.
- Speed up a slow site with Gemini CLIFind out why a site is slow, from real numbers, and learn which fix is a dashboard switch.
- Secure sites and servers with Gemini CLIFind vulnerable sites, manage server firewall rules and banned IPs, and see which protections are on.
Example prompts
What Can You Ask Gemini CLI to Do on xCloud?
Type these as written and swap in your own site and server names. Reads and routine actions such as backups, cache purges, PageSpeed scans and vulnerability scans run straight away; creating, deploying, updating, rebooting, deleting, buying or starting a broken-link scan stops and asks first.
Deploy https://github.com/acme/shop to my Frankfurt server and show me the dry run before you create anything.Update all plugins on example.com, but take a backup first and confirm the homepage still loads afterwards.The last deploy of the API site failed. Diagnose it, fix the build command and retry on the same site.Renew the SSL certificate for shop.example.com and tell me when it expires now.Audit example.com: is it up, is SSL healthy, any vulnerabilities, and how is performance?Good to know
- In settings.json a streamable HTTP server is url plus type set to http, which is what gemini mcp add writes; the older httpUrl key still works. A url without a type is treated as an SSE server and will not connect.
- Do not set trust to true on the xcloud entry. It makes Gemini CLI skip its own tool confirmation dialogs.
- The browser sign-in redirects to a localhost port, so it needs a browser on the same machine. On a remote or headless host, use the API-key form.
- Gemini CLI names tools mcp_xcloud_ followed by the operation name. Use includeTools or excludeTools on the entry if you want a smaller tool list.
More prompts, grouped by job: What you can ask xCloud MCP to do.
Gemini CLI and xCloud: Frequently Asked Questions
Short answers about connecting Gemini CLI, what it may change and what it costs.
How do I connect Gemini CLI to xCloud?
Run gemini mcp add --scope user --transport http xcloud https://app.xcloud.host/mcp in your terminal, then start gemini and ask who you are on xCloud. The --scope user flag registers the server for every project instead of only the current one. Approve the access level in the browser tab that opens the first time.
What is the settings.json form for xCloud?
Under mcpServers add an xcloud entry with url set to https://app.xcloud.host/mcp and type set to http, which is what gemini mcp add writes. Use ~/.gemini/settings.json for every project or .gemini/settings.json for one. The older httpUrl key still works; a url without a type means SSE.
Do I need an xCloud API key for Gemini CLI?
Not when you sign in with OAuth. Gemini CLI finds the authorization endpoints itself and opens your browser. An API key is only for machines without a browser: create a token with the mcp:invoke scope plus the read abilities for the areas it will use (read:servers and read:sites, with read:billing and read:addons for billing and add-on tools) and the matching write: abilities if it should change things and send it in the headers field as an Authorization Bearer value.
What if the sign-in does not start?
Type /mcp auth xcloud inside Gemini CLI to start the OAuth flow by hand. The redirect goes to a localhost port, so run it on a machine that has a browser. Run gemini mcp list to check that the xcloud server is registered.
Can Gemini CLI change my servers without asking?
Not for the operations xCloud gates. Reads run straight away, and routine actions such as cache purges, backups, PageSpeed and vulnerability scans run without a prompt. Creating a site or server, deploying, updating plugins, rebooting, deleting or buying needs an explicit confirmation, and xCloud refuses the call without one.
How do I remove or reconnect the xCloud server?
Run gemini mcp remove xcloud to take it out, then add it again with gemini mcp add. Run gemini mcp list at any time to see which servers are configured and their status.
Can Gemini CLI work across several xCloud teams?
Yes. On the approval screen you tick every team the connection may act on, and you name the team in your request. A site on a team you did not tick comes back as not found; reconnect and tick that team.
Is it free to use Gemini CLI with xCloud?
The xCloud side is free: the MCP server, the skills and the Public API are included with every xCloud account, including the free plan. Gemini CLI itself follows Google's own terms and pricing.
Other agents
Also Works With
The same xCloud account, the same operations, a guide for each client.
- Claude CodeAnthropic's terminal coding agent. One claude mcp add command, plus the xCloud skills plugin with nine skills on top.
- ClaudeAnthropic's chat assistant on the web and desktop. Add xCloud as a custom connector, no terminal needed.
- Claude CoworkAnthropic's desktop agent for delegated work. Add the xCloud connector, then hand off hosting jobs.
- CursorThe AI code editor. One mcp.json entry with the compact URL, because Cursor stops at 40 tools.
- CodexOpenAI's coding agent for the terminal. A codex mcp add command or a config.toml entry, then codex mcp login.
- OpenCodeThe open-source terminal coding agent. One remote MCP entry, then opencode mcp auth xcloud.
- Hermes AgentNous Research's agent with memory and a built-in scheduler. An mcp_servers entry in config.yaml and one login.
- OpenClawThe open-source agent runtime with chat apps and automations. ClawHub skill plus the MCP client.
- WindsurfThe Cognition editor, now Devin Desktop. devin mcp add for the Devin Local agent, a serverUrl entry for legacy Cascade.
- GitHub CopilotCopilot agent mode in VS Code. One .vscode/mcp.json entry, or the Agent Plugins package.
- ChatGPTOpenAI's chat assistant. A developer-mode app with the xCloud MCP URL and OAuth.
- ChatGPT dotsOpenAI's always-on agent in ChatGPT. Uses the xCloud MCP plugin you add in ChatGPT, with custom rules and scheduled tasks.
- GrokxAI's terminal agent, Grok Build. One grok mcp add command or a config.toml entry.
- Grok BotxAI's always-on Bots on a cloud computer. One Remote HTTPS MCP plugin, OAuth sign-in, routines on a schedule.
- KiroAWS's agentic IDE. One url entry in .kiro/settings/mcp.json, plus the portable xCloud Agent Plugins package.
- AntigravityGoogle's agentic IDE. One serverUrl entry in mcp_config.json and a browser sign-in.
- ZedThe Zed editor's Agent Panel. One context_servers entry in settings.json and a browser sign-in.
Run Your Hosting from Gemini CLI
xCloud MCP, the Agent Skills and the Public API are free with every account. Connect once and ask.