Crate

AI-powered music research agent for the terminal

Crate is a CLI tool that helps DJs, record collectors, music journalists, and serious listeners research music in depth. It uses Claude as an AI agent with direct access to multiple music databases, returning structured, cross-referenced results in a rich terminal UI — with built-in audio playback and live radio streaming.

Ask questions in natural language. Crate's agent searches across multiple databases, cross-references results, and presents findings with markdown formatting directly in your terminal.

> Who produced Madvillainy?

Searching MusicBrainz for "Madvillainy"...
Fetching release details...

# Madvillainy (2004)

**Artist:** Madvillain (MF DOOM + Madlib)
**Label:** Stones Throw Records
**Produced by:** Madlib

| # | Track              | Length |
|---|-------------------|--------|
| 1 | The Illest Villains | 2:00  |
| 2 | Accordion          | 2:00  |
...

Play music directly from the conversation:

> Play Accordion by Madvillain

▶ Accordion - Madvillain · MADVILLAINY  ━━━━━━━━━●──────── 1:12 / 2:00  vol:100

Stream live radio from 30,000+ stations worldwide:

> Play some jazz radio

Tuning in to "WBGO Jazz 88.3"...

* Miles Davis - So What · WBGO  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~  LIVE  vol:100

Crate is built for anyone who researches music seriously. Here's what that looks like in practice:

DJ / Radio Programmer — show prep, tracklist building, sample tracing

I'm doing a jazz-to-hip-hop set. Find me 5 jazz records from the
60s-70s that were heavily sampled in 90s boom-bap. For each, give
me the original and the hip-hop track that sampled it.

Record Collector — pressing identification, vinyl valuation, label deep dives

I have a copy of Kind of Blue on Columbia with a "6-eye" label.
What pressing is this, what's it worth, and how do I verify it's
an original vs. a reissue?

Music Journalist — artist profiles, scene reports, credits research

Map the key figures in the Detroit-Berlin techno connection. Start
with the original Detroit producers who had their biggest impact
in Europe.

A&R / Label Scout — artist discovery, catalog analysis, trend mapping

Give me a complete analysis of Stones Throw Records — full catalog,
key artists, genre distribution, and what kind of releases they
focus on.

Serious Listener — deep dives, discovery, playlist building

I want to learn about Afrobeat from the beginning. Give me the
history, who created it, and build me a 15-track chronological
playlist from Fela to today.

Each prompt triggers cross-referencing across multiple databases — no single source has the full picture. See docs/USE_CASES.md for 20 detailed case studies with multi-turn prompt sequences, slash command usage, and advanced workflows.

Crate includes a research-backed influence mapping system based on the Stell-R methodology (Badillo-Goicoechea, Harvard Data Science Review, Fall 2025). The paper demonstrated that artist co-mentions in music reviews — when Pitchfork reviews Radiohead and mentions Aphex Twin in the same paragraph — are a powerful proxy for artistic influence, outperforming collaborative filtering for exploration-oriented discovery.

Crate implements this in three layers:

Review-Driven Discovery — Search 23 music publications using Tavily keyword search (advanced depth) with Exa neural discovery for related reviews. Extract full review text and identify co-mentioned artists using influence phrase detection ("influenced by", "reminiscent of", "in the vein of").

> Search for reviews of Burial's Untrue and extract all influence signals

🔍 Searching music publications for "Burial" — Untrue…
🧬 Extracting co-mentions & influence signals from review text…

Found 8 co-mentions with influence context:
  Massive Attack (3 mentions, influence phrase: "owes a debt to")
  Aphex Twin (2 mentions, influence phrase: "reminiscent of")
  ...

Influence Tracing — Build multi-hop paths between artists using Tavily advanced search for direct connections and Exa neural search for neighborhood discovery. Find bridge artists that connect disconnected genres via Exa crossover search.

> Trace the influence path from Kraftwerk to Radiohead

🔗 Tracing influence path: Kraftwerk → Radiohead

  Kraftwerk
    │ influenced (Wikipedia: "pioneered electronic pop")
    ▼
  Depeche Mode
    │ co-mentioned (Pitchfork review of OK Computer)
    ▼
  Radiohead

Influence Cache — Every discovered connection is persisted to a local SQLite graph (~/.crate/influence.db). Future queries check the cache first for instant results. The graph grows with every question you ask.

> Show me the influence graph stats

📊 247 artists · 512 edges · 1,038 source citations
   Top: Brian Eno (34 connections), David Bowie (28), Aphex Twin (23)

See docs/INFLUENCE-NETWORK.md for the full deep-dive.

MusicBrainz, Wikipedia, Bandcamp, YouTube, Radio Browser, News, Influence Cache, and Telegraph are always available — no API keys needed. The others activate automatically when you provide their API keys.

*Web Search and Influence Network use dual providers — Tavily (keyword) and Exa.ai (neural/semantic). Either key enables both servers; both keys unlock the full toolkit.

*YouTube search works without a key via yt-dlp scraping. Set YOUTUBE_API_KEY for faster, richer search results.

Wikipedia supports optional Wikimedia Enterprise credentials for richer article content, with automatic fallback to free endpoints.

Crate's agent has access to 95 tools across 18 MCP servers. You don't call these directly — describe what you need and the agent picks the right tools automatically. Below is the full reference for what's available.

Sources: Pitchfork, Stereogum, Resident Advisor, The Quietus, BrooklynVegan, Bandcamp Daily, NME, Consequence of Sound, FACT Magazine, NPR Music.

Dual-provider architecture: Tavily handles keyword search with domain filtering and time ranges; Exa.ai handles neural/semantic search and find-similar. Either key enables the server.

Purpose-built tools for tracing artistic influence through music criticism, based on the Stell-R methodology (Badillo-Goicoechea, Harvard Data Science Review, Fall 2025) — which demonstrated that artist co-mentions in 61,000+ album reviews are a powerful proxy for artistic influence and connection.

Persistent local SQLite cache that stores every discovered influence relationship. The graph grows organically over time — the agent checks cache before making expensive web searches.

See docs/INFLUENCE-NETWORK.md for the full deep-dive: research foundation, algorithms, architecture, and how these features compare to streaming service recommendations.

Publish your research as shareable web pages via Telegraph — Telegram's anonymous publishing platform. No API key, no account required.

Publish your music research to your Tumblr blog. Markdown content is automatically converted to Tumblr's NPF (Neue Post Format) with full formatting support — headings, bold, italic, links, lists, blockquotes, and code blocks. Posts are auto-tagged with crate + music and an optional category.

To set up Tumblr publishing:

1. Register an app at tumblr.com/oauth/apps
2. Set TUMBLR_CONSUMER_KEY and TUMBLR_CONSUMER_SECRET in your .env
3. In Crate, ask the agent to connect to Tumblr — it will open your browser for OAuth authorization

Cloud browser powered by Kernel.sh for reading full articles, scraping dynamic pages, and capturing screenshots from sources that block simple HTTP requests (Pitchfork, RateYourMusic, Resident Advisor, etc.).

The agent automatically uses the browser as a fallback when standard HTTP fetches fail due to anti-bot protection or JavaScript-rendered content.

• Node.js 20+
• yt-dlp + mpv — for audio playback (optional)

# macOS
brew install yt-dlp mpv

# Linux
sudo apt install yt-dlp mpv    # or your package manager

npm install -g crate-cli
crate

Or try without installing:

npx crate-cli

Or clone for development:

git clone https://github.com/tmoody1973/crate-cli.git
cd crate-cli
npm install
npm run dev

The built-in setup wizard walks you through API key configuration on first run — no manual .env editing needed.

Crate defaults to Claude Haiku for fast responses. Switch models at startup:

npm run dev              # Haiku (default) — fast lookups
npm run dev:opus         # Opus — deep research
npm run dev:haiku        # Haiku — explicit

Or pass any model directly:

npx tsx src/cli.ts --model sonnet

Crate can run as a standard MCP stdio server, exposing all 95 music research tools to any MCP-compatible client — Claude Desktop, Cursor, OpenClaw, and more.

# Via CLI flag
crate --mcp-server

# Via dedicated binary
crate-mcp

# Via npx
npx crate-cli --mcp-server

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "crate-music-research": {
      "command": "npx",
      "args": ["-y", "crate-cli", "--mcp-server"],
      "env": {
        "DISCOGS_KEY": "your-key",
        "DISCOGS_SECRET": "your-secret",
        "LASTFM_API_KEY": "your-key",
        "GENIUS_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "crate-music-research": {
      "command": "npx",
      "args": ["-y", "crate-cli", "--mcp-server"]
    }
  }
}

Tools are prefixed by server name (e.g. musicbrainz_search_artist, bandcamp_get_album, influence_trace_influence_path). Only servers with configured API keys are exposed — see Environment Variables.

Type / to see all commands in the autocomplete dropdown.

A now-playing bar auto-appears at the bottom of the terminal during playback, showing track info, progress, and volume.

All keys can be managed interactively from within Crate using the /keys command — no need to edit .env manually.

crate-cli/
├── src/
│   ├── cli.ts                 # Entry point, arg parsing
│   ├── mcp-server.ts          # MCP stdio server entry point
│   ├── agent/
│   │   ├── index.ts           # CrateAgent class (wraps Claude Agent SDK)
│   │   └── system-prompt.ts   # Agent personality and tool docs
│   ├── servers/
│   │   ├── index.ts           # Server registry (key-gated activation)
│   │   ├── tool-registry.ts   # Tool aggregator for MCP server mode
│   │   ├── musicbrainz.ts     # MusicBrainz MCP server (6 tools)
│   │   ├── discogs.ts         # Discogs MCP server (9 tools)
│   │   ├── genius.ts          # Genius MCP server (6 tools)
│   │   ├── lastfm.ts          # Last.fm MCP server (8 tools)
│   │   ├── wikipedia.ts       # Wikipedia MCP server (3 tools)
│   │   ├── bandcamp.ts        # Bandcamp MCP server (8 tools)
│   │   ├── youtube.ts         # YouTube player MCP server (4 tools)
│   │   ├── radio.ts           # Radio Browser MCP server (4 tools)
│   │   ├── news.ts            # News / RSS MCP server (3 tools, 10 feeds)
│   │   ├── web-search.ts      # Web search MCP server (3 tools, Tavily + Exa)
│   │   ├── influence.ts       # Influence network MCP server (4 tools, review co-mentions)
│   │   ├── influence-cache.ts # Influence cache MCP server (8 tools, local SQLite)
│   │   ├── telegraph.ts       # Telegraph publishing (5 tools, anonymous pages)
│   │   ├── tumblr.ts          # Tumblr publishing (5 tools, OAuth 1.0a, NPF)
│   │   ├── browser.ts         # Cloud browser (2 tools, Kernel.sh + Playwright)
│   │   ├── collection.ts      # Local collection manager (SQLite)
│   │   ├── playlist.ts        # Playlist manager (SQLite)
│   │   └── memory.ts          # Mem0 persistent memory
│   ├── ui/
│   │   ├── app.ts             # TUI setup, slash commands, progress display
│   │   ├── components.ts      # Themes, banner, hyperlinks
│   │   ├── keys-panel.ts      # Interactive API key management (/keys)
│   │   ├── now-playing.ts     # Now-playing bar overlay
│   │   └── onboarding.ts      # First-run onboarding flow
│   └── utils/
│       ├── config.ts          # Model resolution, env config
│       ├── db.ts              # SQLite database utility (~/.crate/*.db)
│       ├── env.ts             # .env file read/write utilities
│       ├── hints.ts           # Contextual hint engine
│       ├── player.ts          # Shared mpv player infrastructure
│       └── viz.ts             # Terminal visualizations (influence paths, charts)
├── tests/
├── docs/                      # Design docs and plans
├── package.json
└── tsconfig.json

• All external API calls use HTTPS with 15-second AbortController timeouts
• API keys are loaded from environment variables — never hardcoded
• All tool string inputs have maxLength validation via Zod schemas
• Radio stream URLs are validated for HTTP/HTTPS before passing to mpv
• execFileSync with array arguments is used for subprocess calls (prevents shell injection)
• Subprocess events use once() to prevent listener accumulation

npm run dev           # Start dev session
npm test              # Run tests
npm run test:watch    # Watch mode
npm run typecheck     # Type check without emitting

MIT