Bubble Agent MCP

Find the conversations gaining momentum before everyone else.

An open-source Model Context Protocol server that brings live Bubble Agent intelligence into Claude, Codex, Cursor, and every MCP-compatible client.

Website · Install with AI · Quick start · Tools · Security · Contributing

What is a Bubble?

A Bubble is a group of independent internet conversations converging around the same emerging topic. Bubble Agent collects public signals, removes noise, groups related discussions, scores momentum, and preserves the sources behind every result.

This MCP server lets your AI client ask questions such as:

“What are today’s strongest AI infrastructure Bubbles?”
“Why is this conversation growing?”
“Compare these opportunities for a launch.”
“Turn this Bubble into an evidence-based X thread.”

Tools

Tool	What it does	Safety
`get_bubbles`	Returns the highest-priority Bubbles right now	Read only
`search_bubbles`	Searches current and historical conversations	Read only
`get_bubble_details`	Explains momentum, pain points, timeline, and sources	Read only
`compare_bubbles`	Ranks 2–5 Bubbles for a goal	Read only
`generate_content`	Creates a grounded draft from a Bubble	Draft only; never publishes

It also exposes bubble://workspace/profile, a non-sensitive MCP resource containing the company and audience context used for personalization.

Quick start

No-code installation

Download the instruction file for Claude, Codex, Cursor, or another AI agent, attach it to your agent, and say: “Install Bubble Agent MCP for me and verify it works.” The agent will handle the configuration and ask only for your Bubble Agent credentials.

Requirements

Node.js 20 or newer
A Subio account
A project ID and personal API key from subio.space/settings/api-keys

Sign in at subio.space/settings/api-keys, create a key, and copy both values. The API key is shown only once. Never commit it to a repository or paste it into a prompt.

If you run npx -y bubble-agent-mcp without credentials in an interactive terminal, the command opens the secure Subio sign-in page. Create the credentials, add them to your MCP client configuration, and run the command again.

Claude Desktop

Open Claude Desktop settings, choose Developer → Edit Config, and add:

{
  "mcpServers": {
    "bubble-agent": {
      "command": "npx",
      "args": ["-y", "bubble-agent-mcp"],
      "env": {
        "BUBBLE_AGENT_API_KEY": "your_personal_api_key",
        "BUBBLE_AGENT_PROJECT_ID": "your_project_id"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

Copy examples/claude-code.mcp.json to .mcp.json in your project, replace the placeholders, then start Claude Code.

Codex

codex mcp add bubble-agent \
  --env BUBBLE_AGENT_API_KEY=your_personal_api_key \
  --env BUBBLE_AGENT_PROJECT_ID=your_project_id \
  -- npx -y bubble-agent-mcp

Or copy the TOML from examples/codex.config.toml into ~/.codex/config.toml.

Cursor

Copy examples/cursor.mcp.json to .cursor/mcp.json in your project and replace the placeholders.

Any MCP client

Use the standard stdio transport:

command: npx
args: -y bubble-agent-mcp

Set BUBBLE_AGENT_API_KEY and BUBBLE_AGENT_PROJECT_ID in the server environment.

Verify the connection

Run the built-in doctor before configuring your client:

BUBBLE_AGENT_API_KEY=your_personal_api_key \
BUBBLE_AGENT_PROJECT_ID=your_project_id \
npx -y bubble-agent-mcp doctor

Architecture

Claude / Codex / Cursor / MCP client
                 │
                 │ stdio
                 ▼
        Bubble Agent MCP server
                 │
                 │ HTTPS + project-scoped API key
                 ▼
          Hosted Bubble Agent API
          ├─ collection and deduplication
          ├─ clustering and momentum scoring
          ├─ verified source retrieval
          └─ evidence-based content drafts

The open-source package is intentionally thin. It does not contain scraper credentials, database access, private scoring prompts, or provider secrets.

Security

Credentials are read from the MCP process environment, never from tool arguments.
API keys are sent only to the configured Bubble Agent API over HTTPS.
Non-HTTPS remote API URLs are rejected.
The package has no telemetry and does not persist conversation data.
Errors never include the API key.
Generated content remains a draft and is never auto-published.
Keys are project-scoped and can be revoked independently.

Read the full policy in SECURITY.md.

Local development

git clone https://github.com/alijancb/bubble-agent-mcp.git
cd bubble-agent-mcp
pnpm install
cp .env.example .env
pnpm check

Run locally:

BUBBLE_AGENT_API_KEY=your_personal_api_key \
BUBBLE_AGENT_PROJECT_ID=your_project_id \
pnpm dev

Project principles

Evidence before summaries.
Read-only by default.
No publishing without explicit user action.
No provider secrets in the open-source client.
Stable tools that work across MCP clients.

bubble-agent-mcp