cluster-mcp

cluster

The runtime layer for agentic finance on Robinhood Chain. Self-hostable index of AI financial agents — 192 tokenized stocks + native crypto, real Uniswap v3 swaps (non-custodial), persistent memory, and a 24-model LLM gateway.

npx @clusteragent/cluster-mcp

npx skills add clusteragent/cluster        # any skills-CLI agent
pip install cluster-agent                  # Python SDK

Repo Layout

├── SKILL.md                    main installer skill (any agent)
├── index.mjs                   MCP server — 35 tools (@clusteragent/cluster-mcp)
├── skills/
│   ├── swap/                   dedicated swap execution: safety scan → quote →
│   │                           calldata → sign → receipt proof, DCA/bracket patterns
│   ├── trading/                quotes, market data, chart (4663)
│   ├── memory/                 built-in memory + Hindsight backend
│   ├── finance/                portfolio, payouts, keys & metering
│   ├── crypto-intel/           wallet forensics, pool forensics, scout swarm
│   ├── research/               agent roster + OpenBB integration
│   ├── llm-gateway/            24 models, thinking mode, credit accounting
│   ├── portfolio/              wallet valuation, DCA/TP-SL previews
│   ├── social/                 X links + tip intents
│   └── monitor/                price/wallet/cycle/gas watch loops
├── python/                     cluster-agent PyPI SDK
└── docs/self-hosting.md        deployment guide

11 skills total — 1 installer + 10 domain sub-skills.

The cluster backend, frontend and keeper bot are not in this repo — the bot signs real treasury transactions, so the operational stack stays private. This repo is the skill/MCP platform: point it at any cluster deployment.

Quick Start

Agent users — see SKILL.md. MCP config:

{ "mcpServers": { "cluster": {
    "command": "npx", "args": ["-y", "@clusteragent/cluster-mcp"],
    "env": { "CLUSTER_API_URL": "https://clusteragent.dev", "CLUSTER_API_KEY": "clst_...", "CLUSTER_WALLET": "0x..." }
}}}

Self-hosters — see docs/self-hosting.md. Docker images + a deployment guide; SQLite default, zero external services except one LLM key for chat.

Python — see python/:

from cluster import Cluster
c = Cluster(api_url="https://your-host", api_key="clst_...")
c.quotes(["NVDA", "PONS"]); c.payout_basket(); c.chat("hi", thinking=True)

The Mechanism

fees in ──▶ vault ──▶ keeper bot buys the 19-name basket ──▶ $CLST holders paid pro-rata

Holding is the position. Every cycle is public: GET /api/distributions.

Integrations

Project	Role	Guide
Hindsight	learning memory backend (observations, mental models)	skills/memory/
OpenBB	institutional market data (fundamentals, macro) via MCP/Python	skills/research/
Maybe	self-hosted personal finance UI (AGPLv3 — rename your fork)	skills/finance/
OpenCatz	multi-agent scout swarm pattern on 4663	skills/crypto-intel/
Uniswap AI	skills architecture this repo follows	structure

The Agents

Trading Relay · Pivot — Research Scout · Sifter · Quill — Analysis Argus · Prism · Census — Finance Ledger · Remit · Margin — Memory Memoria · Echo — Crypto Nexus · Vault · Oracle

Honesty by Construction

• Pre-launch payout data = honest zeros, never fabricated
• Swaps: API quotes, your wallet signs — no private keys server-side
• Keys: SHA-256 at rest, shown once
• Quote = prediction; receipt = proof (parse the Transfer logs)

License

MIT. Backend and skills are original work. The Maybe Finance fork note applies if you self-host that integration (AGPLv3, trademark rules in skills/finance/).