# Gumball

> Gumball is an open-source MCP server for smart home. Ring, mute and set the volume of a real WiFi siren light from your AI agent. It runs as a hosted remote server, so there is nothing to install locally.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** API, CLI
- **Website:** https://getgumball.com/ai-agents/
- **Repository:** https://github.com/thinkmojo/gumball-mcp
- **MCP Registry name:** io.github.thinkmojo/gumball
- **Categories:** smart home, developer tools
- **Listing updated:** 2026-11-14

## About

This server controls a physical device. Gumball is a WiFi revolving light with a speaker that goes off when something happens, such as a sale, a new user or a deploy. Through MCP an assistant can list your Gumballs, spin one with a chosen sound (0 is light only), play a random sound in a range, set the volume from 0 to 21, and mute or unmute it. With several devices, the agent picks one by name. It cannot change your WiFi, firmware or passwords.

You sign in to a Gumball account, make a named token, and use it either as a Bearer header or inside the address. The address with the token acts like a password. Every agent action is logged against the token's name in the device's activity list, and the limit is 30 actions a minute per token.

A command-line tool, getgumball, talks to the same endpoint. One command, npx getgumball claude-code, adds Claude Code hooks that ring a sound when a task of 30 seconds or more finishes and a different one when Claude needs you, and a short GitHub Actions snippet rings on deploy success or failure. The MCP server is hosted, MIT licensed and made in Montreal by Thinkmojo.

## Features

- **Ring on demand:** Spins the light and plays a numbered sound, or light only.
- **Volume and mute:** Sets volume 0 to 21 and mutes or unmutes notifications.
- **Multiple devices:** Targets a specific Gumball by name or ID.
- **Per-token activity log:** Shows every agent action with the token's name.
- **Claude Code hooks:** One command rings the light when a long task ends or needs input.
- **CI integration:** Ring from GitHub Actions on deploy success or failure.

## Good for

- Get a physical alert when a long Claude Code task finishes
- Signal a failed build or successful deploy in the office
- Silence the office light until tomorrow by asking an assistant
- Play a celebration sound when tests pass

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http gumball https://app.getgumball.com/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://app.getgumball.com/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "gumball": {
      "url": "https://app.getgumball.com/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "gumball": {
      "type": "http",
      "url": "https://app.getgumball.com/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "gumball": {
      "serverUrl": "https://app.getgumball.com/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "gumball": {
      "type": "http",
      "url": "https://app.getgumball.com/mcp"
    }
  }
}
```

## Tools

- `list_gumballs`: Lists your Gumballs with name, ID and online status.
- `ring_gumball`: Spins the light and plays a sound; sound 0 is light only.
- `play_random_sound`: Plays a random sound in a given range.
- `set_volume`: Sets volume from 0 to 21.
- `mute_gumball`: Puts the device in sleep mode, ignoring notifications.
- `unmute_gumball`: Returns the device to normal.

## FAQ

### What do I need?

A Gumball device, a Gumball account and a token made on the AI agents page.

### Is there a rate limit?

Yes, 30 actions a minute per token.

### How do I revoke access?

Delete the token on your account page; one token per app lets you cut off one without affecting others.

### Can ChatGPT ring it?

The site says ringing is a write action that OpenAI does not allow on every plan yet.

### Is Gumball free?

Yes. Gumball is open source, so you can use and self-host it for free.

### How do I add Gumball to Claude Code?

Run this command in your terminal: claude mcp add --transport http gumball https://app.getgumball.com/mcp

### What are the best alternatives to Gumball?

The closest alternatives to Gumball are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/gumball
