npm package: @revelator-music/mcp-server
Description: MCP server for Revelator platform APIs - music distribution, royalties, catalog management
Author: Revelator
Latest version: 0.1.5

# Revelator MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with access to the Revelator platform APIs for music distribution, catalog management, royalties, blockchain, and more.


## Installation

```bash
npm install @revelator/mcp-server
```

Or install globally:

```bash
npm install -g @revelator/mcp-server
```


## Authentication

Revelator uses two authentication methods:

| Method | Header Format | Use Case |
|--------|---------------|----------|
| **Partner API Key** | `Authorization: <key>` | Admin endpoints, provided during partner onboarding |
| **Access Token** | `Authorization: Bearer <token>` | User-authenticated requests, valid for 8 hours |

### Getting an Access Token

Use the `auth_login` tool to authenticate and receive an access token (valid for 8 hours):
- Provide `partnerApiKey` plus either `username`/`password` (prompted login) or `partnerUserId` (automated login)

For new users, use `auth_signup` to create an account first. Use `auth_forgot_password` to initiate a password reset.

<details>
<summary>Manual API call</summary>

```bash
curl -X POST https://api.revelator.com/partner/account/login \
  -H "Content-Type: application/json" \
  -d '{
    "partnerApiKey": "your-partner-api-key",
    "username": "user@example.com",
    "password": "userpassword"
  }'
```

</details>

See [Revelator API Docs](https://api-docs.revelator.com/en/getting-started) for full authentication details.


## Configuration

Set your credentials as environment variables:

```bash
# Option 1: Partner API Key (for admin/partner endpoints)
export REVELATOR_PARTNER_API_KEY=your-partner-api-key

# Option 2: Access Token (for user-authenticated requests)
export REVELATOR_ACCESS_TOKEN=your-access-token
```

If both are set, the access token takes precedence.


## Usage with Claude Desktop

Add to your Claude Desktop configuration (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "revelator": {
      "command": "npx",
      "args": ["@revelator/mcp-server"],
      "env": {
        "REVELATOR_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}
```

Or with Partner API Key:

```json
{
  "mcpServers": {
    "revelator": {
      "command": "npx",
      "args": ["@revelator/mcp-server"],
      "env": {
        "REVELATOR_PARTNER_API_KEY": "your-partner-api-key"
      }
    }
  }
}
```


## Available Tools (61 total)

### Auth Tools (3)
| Tool | Description |
|------|-------------|
| `auth_login` | Authenticate and get an access token (valid 8 hours) |
| `auth_signup` | Create a new Revelator account and user |
| `auth_forgot_password` | Initiate password reset flow |

### Analytics Tools (5)
| Tool | Description |
|------|-------------|
| `analytics_consumption_by_track` | Get streaming consumption data by track |
| `analytics_consumption_by_artist` | Get streaming consumption data by artist |
| `analytics_consumption_by_release` | Get streaming consumption data by release |
| `analytics_artificial_streams_by_track` | Get artificial/suspicious streaming activity (fraud detection) |
| `analytics_artificial_streams_dashboard` | Get artificial streams dashboard metrics |

### Blockchain Tools (11)
| Tool | Description |
|------|-------------|
| `blockchain_list_royalty_tokens` | List royalty tokens |
| `blockchain_get_royalty_token` | Get royalty token details |
| `blockchain_get_token_holders` | Get current holders of a royalty token |
| `blockchain_check_isrc_duplicate` | Check if track ISRC is already tokenized |
| `blockchain_get_token_count` | Get total royalty token count |
| `blockchain_search_payees` | Search blockchain payees |
| `blockchain_get_payee` | Get blockchain payee details |
| `blockchain_get_payee_wallet` | Get payee wallet details |
| `blockchain_get_balance` | Get wallet balance on a network |
| `blockchain_get_transaction` | Get transaction details by hash |
| `blockchain_get_smart_wallet_transactions` | Get smart wallet transactions |

### Catalog Tools (5)
| Tool | Description |
|------|-------------|
| `catalog_search_tracks` | Search tracks by title, artist, or ISRC |
| `catalog_get_track` | Get detailed track information |
| `catalog_search_releases` | Search releases (albums, singles, EPs) |
| `catalog_get_release` | Get detailed release information |
| `catalog_list_labels` | List record labels |

### Core Tools (6)
| Tool | Description |
|------|-------------|
| `core_get_whitelabel` | Get white-label branding configuration |
| `core_get_user_permissions` | Get permissions for a user |
| `core_list_artists` | List artists with filtering |
| `core_list_payees` | List payees with filtering |
| `core_list_youtube_channels` | List YouTube MCN channels |
| `core_submit_feedback` | Submit user feedback |

### Distribution Tools (8)
| Tool | Description |
|------|-------------|
| `distro_get_acrcloud_results` | Get audio fingerprint analysis from ACRCloud |
| `distro_get_asset_monetization` | Get monetization policies for an asset |
| `distro_list_monetization_policies` | List available monetization policy options |
| `distro_get_release_pricing` | Get pricing tiers for a release |
| `distro_get_pricing_options` | Get available pricing tier options |
| `distro_get_release_monetization` | Get track-level monetization policies |
| `distro_get_territory_clearances` | Get territorial distribution clearances |
| `distro_get_watchlist_matches` | Get watchlist matches (potential conflicts) |

### Generic API Tools (15)
| Tool | Description |
|------|-------------|
| `generic_get_current_user` | Get current user profile |
| `generic_get_sessions` | Get active user sessions |
| `generic_get_permissions` | Get user permissions and access levels |
| `generic_list_payees` | List all payees |
| `generic_get_payee` | Get payee details |
| `generic_get_payee_insights` | Get payee analytics and insights |
| `generic_get_payee_balance` | Get payee balance information |
| `generic_list_contracts` | List all contracts |
| `generic_get_contract` | Get contract details |
| `generic_get_contract_summary` | Get contract summary data |
| `generic_list_transactions` | List payment transactions |
| `generic_get_transactions_grouped` | Get grouped transaction analysis |
| `generic_get_playlist_analytics` | Get playlist performance analytics |
| `generic_get_playlist_movements` | Get track positioning changes in playlists |

### Payments Tools (3)
| Tool | Description |
|------|-------------|
| `payments_list_external_accounts` | List external payment accounts |
| `payments_get_bridge_account` | Get Bridge payment integration account |
| `payments_get_bamboo_account` | Get Bamboo payment integration account |

### Royalties Tools (5)
| Tool | Description |
|------|-------------|
| `royalties_list_contracts` | List royalty contracts |
| `royalties_get_contract` | Get contract details |
| `royalties_list_statements` | List payee statements |
| `royalties_list_runs` | List royalty processing runs |
| `royalties_list_sales_reports` | List sales reports |


## API Domains

| Domain | Base URL | Description |
|--------|----------|-------------|
| Analytics | platform.revelator.com/analytics | Streaming metrics, fraud detection |
| Blockchain | platform.revelator.com/blockchain | Royalty tokens, wallets, on-chain |
| Catalog | platform.revelator.com/catalog | Tracks, releases, labels |
| Core | platform.revelator.com/core | Users, permissions, integrations |
| Distro | platform.revelator.com/supply-chain | Monetization, pricing, distribution |
| Generic | api.revelator.com | Legacy API, accounting, contracts |
| Payments | platform.revelator.com/payments | External accounts, payment integrations |
| Royalties | platform.revelator.com/royalties | Contracts, statements, runs |


## License

[MIT](LICENSE)