Bandmate MCP Server

An MCP (Model Context Protocol) server that provides access to the Bandmate REST API for managing songs and lists with chord notations.

Installation

cd bandmate-mcp
npm install
npm run build

Configuration

Set the following environment variables:

Usage with Claude Code

Add to your Claude Code MCP configuration (~/.claude/mcp_settings.json):

{
  "mcpServers": {
    "bandmate": {
      "command": "node",
      "args": ["/path/to/bandmate-mcp/dist/index.js"],
      "env": {
        "BANDMATE_API_URL": "https://vertigox.ue.r.appspot.com/api",
        "BANDMATE_AUTH_TOKEN": "your-firebase-token"
      }
    }
  }
}

Or using npx (after publishing):

{
  "mcpServers": {
    "bandmate": {
      "command": "npx",
      "args": ["bandmate-mcp"],
      "env": {
        "BANDMATE_AUTH_TOKEN": "your-firebase-token"
      }
    }
  }
}

Available Tools

Song Tools

List Tools

Tool Parameters

get_songs

• userId (optional): Filter to user's songs + public songs

• ids (optional): Comma-separated song IDs to fetch

get_song

• id (required): Song ID

get_songs_by_user

• userId (required): User ID

get_songs_in_list

• listId (required): List ID

upsert_song

• id (optional): Song ID for updates

• title (required): Song title

• chordsText (required): Chord notation and lyrics

• isPublic (optional): Public visibility (default: false)

• bpm (optional): Beats per minute

• key (optional): Musical key

• voice (optional): Vocal range

• tags (optional): Array of tags

• spotifyUrl (optional): Spotify link

• youtubeUrl (optional): YouTube link

• userId (optional): Creator user ID

get_lists

• userId (optional): Filter to user's lists + public lists

get_list

• id (required): List ID

upsert_list

• id (optional): List ID for updates

• name (optional): List name

• isPrivate (optional): Private visibility (default: false)

• songs (optional): Array of song IDs

• userId (optional): Owner user ID

search_songs

• query (required): Search term

• userId (optional): Include user's private songs

Development

# Run in development mode
npm run dev

# Build for production
npm run build

# Run production build
npm start

Deployment to Google Cloud Run

This MCP server uses SSE (Server-Sent Events) transport, making it deployable as a remote HTTP service.

Prerequisites

1. Install the Google Cloud CLI

2. Authenticate: gcloud auth login

3. Set your project: gcloud config set project YOUR_PROJECT_ID

Deploy

# Build and deploy in one command
gcloud run deploy bandmate-mcp \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \

# Or with authentication token
gcloud run deploy bandmate-mcp \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \

Endpoints

Local Docker Testing

# Build the image
docker build -t bandmate-mcp .

# Run locally
docker run -p 8080:8080 \
  -e BANDMATE_API_URL=\
  bandmate-mcp

# Test health endpoint
curl http://localhost:8080/health

License

MIT