tribe-mcp

Standalone MCP server that exposes TRIBE brand data — neural fingerprints, organic posts, and brands — from a Turso (libsql) database to MCP clients like Claude. Lets you do brand-grounded analysis over real data. No app or dashboard required; it only needs a Turso DB with the expected tables.

Tools

Tool	What it does
list_brands	Discover brand IDs to use with the other tools.
list_fingerprints	List TRIBE fingerprints (filter by brand / label).
get_fingerprint	Pull a full fingerprint with channels + timeline by ID.
compare_fingerprints	Pull two fingerprints side-by-side for A/B analysis.
list_organic_posts	List Instagram + TikTok posts logged for a brand.
get_organic_post	Pull a single organic post with its retention curve.
write_insight	Persist an analysis back to the DB so other tools/UIs can read it.

Setup

Requires Node 18+ and a Turso database (the tables are defined in src/db.ts).

git clone https://github.com/<you>/tribe-mcp.git
cd tribe-mcp
npm install
cp .env.example .env          # fill in TURSO_DATABASE_URL + TURSO_AUTH_TOKEN
npm run build

Smoke-test:

TURSO_DATABASE_URL=... TURSO_AUTH_TOKEN=... npm start
# prints "tribe-mcp ready (stdio)" then waits for MCP messages; Ctrl-C to exit.

Connect to Claude

Claude Code (available in every project):

claude mcp add tribe -s user \
  -e TURSO_DATABASE_URL="libsql://<your-db>.turso.io" \
  -e TURSO_AUTH_TOKEN="<your-token>" \
  -- node /ABSOLUTE/PATH/TO/tribe-mcp/dist/index.js

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tribe": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/tribe-mcp/dist/index.js"],
      "env": {
        "TURSO_DATABASE_URL": "libsql://<your-db>.turso.io",
        "TURSO_AUTH_TOKEN": "<your-token>"
      }
    }
  }
}

Restart the client; the tribe tools appear in conversation.

The model (Modal) — modal_app.py

modal_app.py is the inference backend that produces the fingerprints this MCP reads. It runs Meta FAIR's TRIBE v2 brain-encoding pipeline on a Modal GPU:

video URL / upload
  → yt-dlp + ffmpeg
  → V-JEPA2 (video) + Wav2Vec2 (audio) + LLaMA (transcript text)  features per fMRI TR
  → TRIBE v2 brain encoder → Schaefer-400 / 7-network parcel time-series (T × 400)
  → reduce to 9 channels + global stats + nilearn 3D brain + Whisper transcript
  → Fingerprint JSON  (stored in Turso → served by this MCP)

Endpoints (deployed at https://<workspace>--api.modal.run): POST /start → job_id, GET /poll?job_id=… → running|complete|error, GET /health, plus /serve_brain, /serve_video, /predictions.

Deploy

pip install modal && modal token new          # one-time
# optional Bearer auth (recommended for a public endpoint):
modal secret create tribe-api-key TRIBE_API_KEY="$(openssl rand -base64 32)"
modal deploy modal_app.py
curl https://<workspace>--api.modal.run/health   # {"status":"ok","atlas":"schaefer_400_7networks_v1",...}

TRIBE weights

Set TRIBE_CKPT (a path baked into the image or on the mounted Volume) to Meta's trained TRIBE v2 brain-encoder checkpoint. Without it, a deterministic placeholder encoder runs so the whole app is end-to-end testable — its numbers are structurally valid but not real brain predictions.

⚠️ Reconstruction + license. The original tribev2-by-meta/modal_app.py was lost; this file is reconstructed from the dashboard's exact API contract + design doc — the serving contract and feature pipeline are faithful; supply the checkpoint for real predictions. TRIBE v2 is CC BY-NC (research only) — this wrapper is MIT, but the model weights are not; don't ship client-facing deliverables from its outputs without a commercial license from Meta.

License

MIT — see LICENSE. (Applies to this wrapper code, not the TRIBE v2 weights.)