Bling Bag MCP server

Bling Bag

Give your bot an identity.

Your bot has a name. Now give it a personality, a look, and a backstory.

Roll the wheel and see what you get — or write your own in a bling.json file.

What you get

Five MCP tools and two identity pools:

WOW — Weird Office Workers

Roll a random quirky office-worker bot: name, job title, desk setup, habits, coffee ritual, and a screenshot-ready share card. 99/99 tests, full rarity engine, 13 weighted trait pools.

Legends — Historical Figures

Same engine, different universe. Roll a historical figure in an absurd corporate role — Julius Caesar as Hostile Takeover Specialist, Marie Curie as Lab Safety's Most Wanted, Napoleon as Regional Manager (France & Surrounding Areas).

Pass variant: "legends" to roll_identity to use it. Default is "wow".

Install

Prerequisites

• Node.js 20 or later
• An MCP-compatible client (Claude Code, Claude Desktop, Codex, Cursor, etc.)

Add the package

npm install bling-bag

Or run it on-demand without installing — MCP clients can launch it directly via npx bling-bag (see client config below).

For development (modifying the source)

git clone https://github.com/<github-user>/mcp-bling.git
cd mcp-bling
npm install
npm run build

Produces a runnable server at dist/index.js.

Wire it into your MCP client

The server uses stdio transport — clients launch it as a child process, not over a network port.

Claude Code

Add to your Claude Code MCP config (location varies by version):

{
  "mcpServers": {
    "bling": {
      "command": "npx",
      "args": ["-y", "bling-bag"],
      "env": {
        "BLING_PATH": "/absolute/path/to/your/bling.json"
      }
    }
  }
}

npx -y bling-bag downloads and runs the latest version without requiring a separate install step.

Claude Desktop

Same shape, in claudedesktopconfig.json:

{
  "mcpServers": {
    "bling": {
      "command": "npx",
      "args": ["-y", "bling-bag"],
      "env": {
        "BLING_PATH": "/absolute/path/to/your/bling.json"
      }
    }
  }
}

Pinning to a version (recommended for production)

To avoid picking up future releases automatically, pin a specific version:

"args": ["-y", "bling-bag@0.1.0"]

Developer-mode invocation (from a local clone)

If you've cloned the repo and want to run from dist/ directly, use:

"command": "node",
"args": ["/absolute/path/to/mcp-bling/dist/index.js"]

If BLING_PATH is not set, the server looks for ./bling.json in its working directory.

Config resolution order

The server resolves the bling config path in this order:

1. --bling CLI argument (highest priority)
2. BLING_PATH environment variable
3. ./bling.json in the server's working directory (default)

bling.json — the bot's identity file

Three fields are required: name, personality (with tone, formality, humor), and theme (with primarycolor and accentcolor as #RRGGBB hex strings).

Minimum example

{
  "name": "Pixel",
  "personality": {
    "tone": "warm",
    "formality": "casual",
    "humor": "playful"
  },
  "theme": {
    "primary_color": "#3A7BD5",
    "accent_color": "#FFD166"
  }
}

Full example (with all optional sections)

Shortened. The full README is on GitHub.