@labelgrid/mcp

LabelGrid MCP Server

@labelgrid/mcp — the official Model Context Protocol server for LabelGrid, the music distribution platform. Point Claude Desktop, Claude Code, Cursor, or any MCP client at your own LabelGrid account and manage your music catalog, releases, files, analytics, royalty accounting, webhooks, and distribution in natural language — 30 consolidated tools forming a thin, typed wrapper over the LabelGrid public API, so every rule and validation stays on the server.

Quickstart

You need a LabelGrid API token (see Getting a token) and Node.js 20+. The server runs on demand via npx — nothing to install globally.

Claude Desktop — one-click install

The quickest way in, with no config file to edit:

• Download labelgrid.mcpb from the latest release.
• Double-click it, or open Claude Desktop → Settings → Extensions and drag the file in.
• When prompted, paste your LabelGrid API token — or leave it blank and let the in-chat guided setup walk you through creating one.

To update later, download the newer .mcpb and install it over the old one. Prefer to configure it yourself, or using a different client? The manual npx setup below works everywhere.

Claude Desktop — manual config

Add this to your claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "labelgrid": {
      "command": "npx",
      "args": ["-y", "@labelgrid/mcp"],
      "env": {
        "LABELGRID_API_TOKEN": "your-token-here"
      }
    }
  }
}

Restart Claude Desktop. You should see the LabelGrid tools appear.

Claude Code

claude mcp add labelgrid -e LABELGRID_API_TOKEN=your-token-here -- npx -y @labelgrid/mcp

Cursor

Add this to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "labelgrid": {
      "command": "npx",
      "args": ["-y", "@labelgrid/mcp"],
      "env": {
        "LABELGRID_API_TOKEN": "your-token-here"
      }
    }
  }
}

First run / setup mode

If you start the server without LABELGRID_API_TOKEN, it does not fail — it launches in setup mode: the full tool catalog stays listed so you can see what the server offers, and a setup helper leads the way. Nothing can run in this state — every catalog tool returns setup guidance instead. Just ask your AI client to "set up LabelGrid" and it will walk you through creating a token and adding it to your config. Once the token is set, restart your client and the tools go live.

Getting a token

API access is part of LabelGrid's API plans — see the API Overview and Quickstart for what the API offers and how to activate it.

• Sign in to your LabelGrid dashboard.
• Go to Profile → API Tokens. (If you don't see this option, your account doesn't have API access yet — the API overview explains how to get it, or contact support.)
• Create a token and copy it into your client config as LABELGRID_API_TOKEN.

Treat the token like a password: it grants access to your catalog. Never commit it or paste it into a shared chat. Revoke a token any time from the same screen (or with the revoke_api_token tool).

Configuration

All configuration is via environment variables in your client config.

Variable	Default	Purpose
LABELGRID_API_TOKEN	—	Required. Your API token.
LABELGRID_API_URL	production API	Override the API base URL.
LABELGRID_ENABLE_WRITES	true	Safe writes (create/update drafts, labels, artists, …). Set false for reads only.
LABELGRID_ENABLE_FULL_WRITES	false	Arm full writes — see Safety model. Also requires the acknowledgment below.
LABELGRID_FULL_WRITES_ACK	—	Must equal the exact acknowledgment sentence to arm full writes.
LABELGRID_READ_ONLY	false	Force reads only; overrides both write flags.
LABELGRID_TOOLSETS	all except webhooks	Comma-separated subset of toolsets to expose.
LABELGRID_TIMEOUT_MS	60000	JSON request timeout in milliseconds. Must be a positive integer; a bad value is ignored with a warning.
LABELGRID_TRANSFER_TIMEOUT_MS	600000	Upload/download transfer timeout in milliseconds (for presigned uploads and statement downloads). Same validation.
LABELGRID_DOWNLOAD_DIR	~/Downloads if it exists, else the working directory	The only directory download_statement may write a save_to_path into; a path outside it is refused.

Valid toolsets (8): account, reference, catalog, releases, insights, finance, webhooks, distribution.

• webhooks is opt-in: it is excluded from the default surface. Name it explicitly in LABELGRID_TOOLSETS (e.g. LABELGRID_TOOLSETS=webhooks or catalog,releases,webhooks) to enable the webhook tools.
• Legacy toolset names from 0.2.x (identity, review, delivery, analytics, accounting) are still accepted in LABELGRID_TOOLSETS and map silently to their current toolset (account, releases, releases, insights, finance).

The nine reference datasets are also exposed as MCP resources at labelgrid://reference/{type}; the list_reference_data tool serves the same data for clients that don't surface resources.

Tool reference

33 tools across 8 toolsets. This table is generated from the tool definitions by npm run gen-docs — do not edit it by hand.

Account account

Tool	Gate	Description
get_account	read	Read the authenticated LabelGrid account. Pick ONE view with view: profile returns the account profile — including the release submission limit/quota and terms-acceptance status — use it to confirm which account your API token belongs to before making other calls; balance returns your accounting summary — current balance and related account-level financial totals.
get_rate_limit	read	The account’s API rate budget per category (read, write, export, analytics): ceiling, remaining, and window reset. Every token on the account shares one budget; a null ceiling means none applies. Free to call — use it to pace requests and to recover from a 429.
revoke_api_token	write	Revoke a LabelGrid API token. Pass token_id to revoke a specific token; omit it to revoke the token currently in use. WARNING: revoking the current token immediately ends this session — the server loses access and stops working until you configure a new token.

Reference data reference

Tool	Gate	Description
list_reference_data	read	Fetch a LabelGrid reference dataset used to resolve the IDs and codes the catalog and release tools expect. Pick ONE dataset with type: genres and genre_categories (genre IDs), languages (audio/metadata language codes), contributor_roles, instruments, distro_outlets (the outlets/stores available to you), territories (country codes), issue_definitions (review issue codes — string slugs — with severity and whether they block distribution), or webhook_event_types (event types with their payload schemas). Also exposed as MCP resources at labelgrid://reference/{type}; this tool is the fallback.

Catalog (labels, artists, writers, publishers, releases, tracks) catalog

Tool	Gate	Description
search_catalog	read	List catalog entities of one kind, paginated. filters takes the endpoint’s own filter names, passed through verbatim — label: no documented filters. artist: artist_name. writer: name, ipi. publisher: name, ipi. release: label_id, is_live (1 = live only), barcode_number (UPC/EAN), cat. track: release_id, isrc. Use get_catalog_item for full detail.
get_catalog_item	read	Retrieve one catalog entity by id, with full detail (e.g. a release’s metadata and track listing, a track’s contributors and royalty splits, a writer’s PRO/IPI).
create_catalog_item	write	Create a catalog entity: pass its attributes in fields — the API owns all validation. Required and common fields per entity: label — required: name, default_email; optional: support email, website/platform URLs, default copyright lines, isrc_base. artist — required: artist_name; optional: full_name, email, location, bios, isni, default_language, platform profile URLs. writer — required: first_name, last_name; optional: middle_name, display_credits, email, country, pro, ipi, isni, publisher_id (or publisher_name/publisher_pro/publisher_ipi). publisher — required: name; optional: ipi, pro, isni, controlled_publisher. release — required on create: content_type, label_id, artists, titles, cat (catalog number), artwork_ai_usage, primary_genre_id; many optional fields (dates, copyright lines, genres, per-outlet URLs). track — required on create: release_id, disc, track_num, composition_type, artists, audio_ai_usage, composition_ai_usage, commercial_samples, audio_language, contributors, and recording_country (ISO 3166-1 alpha-2, e.g. "US"); optional: titles, isrc, iswc, writers, publishers, splits, and more. A release is created in DRAFT state — add tracks, then run the release checks before distributing.
update_catalog_item	write	Update a catalog entity: supply only the fields to change in fields (same field sets as create_catalog_item). Once a release is submitted or distributed, some release and track fields are locked — changing one returns a 403 with code RELEASE_LOCKED_FIELDS naming exactly which fields cannot change.
delete_catalog_item	write	Delete a catalog entity. The API refuses deletes that would orphan data — label: refused while the label still has releases — remove or reassign its releases first. artist: refused while still referenced by releases or tracks. writer: refused while still referenced by tracks. publisher: refused while still referenced by writers. release: only a never-submitted draft can be deleted. track: refused once the release is no longer an editable draft.
upload_image	write	Upload a label image (logo, dark-mode logo, or background) or an artist photo from a local image file, per target.
get_asset	read	Read a track or release asset. Valid combinations: (1) mode='info' + parent='track' + asset stereo|dolby|lyrics — file metadata (not the bytes) incl. processing state. (2) mode='info' + parent='release' + asset square|tall — motion-artwork (animated cover) video metadata. (3) mode='download_url' + parent='track' + asset audio_16|audio_24|audio_32 (WAV master) or audio_preview_full|audio_preview_clip (MP3 preview) — returns { download_url, expires_in }, a signed URL that expires roughly 10 minutes after issue; fetch it directly — do not send your API token to it. Any other combination is refused.

Releases (review, delivery, links, licenses, checks) releases

Tool	Gate	Description
get_release_review	read	Read a release's automated quality-check results. Pick ONE view with view: issues lists the review issues raised against the release — each with a code (see list_reference_data type issue_definitions), severity, and whether it blocks distribution. quality_report returns the Preflight QC quality report — customer-facing issues to review before confirming distribution; Preflight QC is an optional add-on — without it the API returns a 403, surfaced verbatim.
get_delivery_queue	read	List your account's distribution queue, paginated — one entry per (release, outlet) delivery with its status (e.g. pending review, processing, scheduled, complete, error). Filter by release_id, outlet_id, or status.
get_landing_config	read	Retrieve a release's smart-link landing-page configuration: enabled state, style/mode, custom copy, action list, pre-order links. Change it via manage_release_links (action update_landing_config).
list_track_licenses	read	List a track's licenses (e.g. cover/mechanical or sample clearances), paginated. Pass license_id to retrieve one license instead.
run_release_checks	write	Run an automated check on a release. Pick ONE with check: validate returns problems that would block distribution (human-readable errors + machine-readable errors_structured); it changes nothing and is safe to repeat — run it before distributing. refresh_quality_report re-runs the Preflight QC checks (read the report with get_release_review view quality_report); an hourly refresh budget may rate-limit frequent calls. Preflight QC is an optional add-on.
manage_release_links	write	Manage a release's smart-link landing page. Pick ONE action with action: update_landing_config replaces the configuration with config (required for this action) — config.actions uses the v2 action-list contract (one entry per call-to-action); other keys: links_page_enabled, config_mode, page_style, custom_cta_text, custom_description, pre_order_links. create_short_url creates (or returns the existing) short URL for the landing page — safe to repeat.
add_review_issue_note	write	Add a note to a release review issue — to explain a fix or add reviewer context. review_issue_id comes from get_release_review view issues.

Insights (analytics & artificial streaming) insights

Tool	Gate	Description
get_analytics	read	Streaming analytics summary. Window capped at 400 days; metrics takes 1-12 section keys per request (split larger selections; responses cached). KUGOU/KUWO/QQMUSIC report weekly: one point carries the whole week — never average per day. meta carries platform_cadence, section_granularity, sections_as_of and sections_complete_through (later dates still filling in). See get_analytics_availability for per-platform support. Sections aggregate over the resolved filter scope: a upc filter gives release totals, not per-track rows. For those use track-*-daily (needs a release_id, isrc or upc scope) or get_analytics_rankings. track-listeners-daily sums per-entry daily counts: not distinct people, not summable across dates. social-* / soundcloud-engagement cover social/UGC usage, not streaming: platform is a UGC platform, ugc_platform narrows them; use, view and play are distinct quantities never summed together or with streams. Selecting any adds meta.social_availability (which UGC platforms report each signal); the streaming matrix omits them. Rate-limited ~60/min; windows over 90 days draw a separate ~30/min budget — prefer short windows for polling. A 429 carries retry_after_seconds.
get_analytics_availability	read	Static availability matrix (per section, per platform) plus platform_cadence (daily|weekly per platform). Account- and date-independent: fetch once, reuse. Read it before get_analytics so an unreported section is treated as unavailable, not an empty chart.
get_analytics_rankings	read	Top-N rankings for a window, ordered by summed streams — the per-entity breakdown of a scope: type tracks with a upc/release_id filter ranks the tracks on that release. Pick ONE view: leaderboards — your top artists, tracks or albums (type required; all returns all three in one call). placements — playlists and radio containers driving streams, summed across storefronts. Same scope filters as get_analytics; limit 1-50 (default 10). Under a platform filter, availability: not_available_for_platform means no ranking there and data is empty.
query_artificial_streaming	read	Artificial-streaming (streaming-integrity) reads. Pick ONE view: flags — Stream Radar early-warning flags, paginated (filters: status, severity, dsp, isrc, release_id, detected_from/detected_to). Stream Radar is an optional add-on; without it the API returns a 403, surfaced verbatim. flag_detail — one flag by flag_id. records — reported artificial-streaming records, cursor-paginated; the detail behind any artificial-streaming fee (filters: dsp, start_date/end_date, release_id, isrc). fee_breakdown — per-release fee breakdown for one period (YYYY-MM). response_format:'detailed' returns the verbatim API response.

Finance (statements, transactions, royalties) finance

Tool	Gate	Description
query_financials	read	Query your financial data. Pick ONE view with view: statements lists your royalty statements, paginated — filters: label_id, release_id, isrc, upc, start_date/end_date; group_by="release" rolls totals up per release. statement_detail retrieves one statement by invoice_number (required). transactions lists account transactions, paginated — same filters and group_by; sort with sort. royalty_breakdown returns a cursor-paginated royalty breakdown — group_by is REQUIRED for this view: a comma-separated, ordered subset of: track, dsp, release, territory, period (e.g. "release,dsp"); same filters; pass cursor to page. Use download_statement for statement line items (CSV) or the invoice PDF. response_format:'detailed' returns the verbatim API response.
download_statement	read	Download statement files. format: 'csv' downloads statement line items — pass invoice_number for one statement, OR a start_date/end_date range to export across statements; with save_to_path the CSV is written there and the byte count returned; otherwise it is returned inline, truncated at 100KB (truncated: true) — use save_to_path for large exports. format: 'invoice_pdf' downloads the invoice PDF — invoice_number and save_to_path are both REQUIRED (the PDF is binary). An existing file is never overwritten (returns FILE_EXISTS).

Webhooks (off by default — enable via LABELGRID_TOOLSETS) webhooks

Tool	Gate	Description
list_webhooks	read	Read your webhook subscriptions. view: 'config' (the default) lists them — URL, subscribed events, active state — or retrieves one when webhook_id is given. view: 'logs' retrieves the recent delivery log for a webhook (webhook_id required) — attempts, response codes and outcomes — to debug why events did or did not reach your endpoint.
manage_webhook	write	Manage a webhook subscription. Pick ONE action with action: create — fields: name, url (the HTTPS endpoint receiving deliveries), events (see list_reference_data type webhook_event_types); the signing secret is returned ONCE on creation — store it to verify payloads. update — supply only the fields to change in fields: name, url, events, or is_active (false pauses deliveries). delete — permanently removes the subscription. test — sends a test event to confirm reachability and signature verification. rotate_secret — returns a new signing secret — WARNING: the old secret stops working immediately; update your endpoint or deliveries fail verification. webhook_id is required for every action except create.

Distribution (full writes) distribution

Tool	Gate	Description
upload_asset	full-write	Upload a finalized track or release asset from a local file. track_stereo (WAV/FLAC/AIFF), track_dolby (Dolby Atmos WAV) and track_lyrics (LRC) process asynchronously — check state with get_asset (mode info). release_cover_art uploads or replaces the static cover art image. release_motion_square/release_motion_tall upload the animated cover (motion artwork) video, also asynchronous. All assets become immutable once the release is distributed — upload final files first.
delete_asset	full-write	Delete a track asset (track_) or an animated cover / motion artwork video (release_motion_). Allowed only while the parent release is an editable draft; refused once locked or distributed. Cover art cannot be deleted.
manage_track_license	full-write	Manage license documents on a track (cover or cleared sample). upload attaches a new license — file_path required, type selects cover/sample; optional metadata fields. update replaces the file and/or metadata — track_license_id (from list_track_licenses) and file_path required. delete permanently removes a license and its file — track_license_id required; cannot be undone. Immutability-governed once the release is live.
distribute_release	full-write	Submit a release to the stores/outlets — the FINAL action that sends it out; run_release_checks (check validate) should pass first. The server enforces the account’s weekly submission limit. Reuse the SAME idempotency_key when retrying an unobserved call; without one each call is a new submission.
takedown_release	full-write	Take a release down from ALL outlets/stores — a final action that removes it everywhere it was delivered. Re-distribution is a fresh submission.
confirm_review	full-write	Confirm a release Preflight QC placed on hold, moving it into distribution review, after reviewing the quality report and accepting the release as-is. Safe to repeat.
enable_beatport	full-write	Request Beatport onboarding for a label. One-time and cannot be un-requested — confirm the label is correct first.

Migrating from 0.2.x

Version 0.3.0 is a breaking release: the 83 per-endpoint tools were consolidated into 30 tools that select their target with an argument (entity, view, action, check, format, target, type). Every 0.2.x capability is preserved — the table below maps each old tool to its new call. Toolsets were regrouped into eight sets (legacy set names are still accepted as aliases in LABELGRID_TOOLSETS), and the webhooks toolset is now off by default.

Old tool (0.2.x)	New call (0.3.0)
get_me	get_account (view: 'profile')
get_account_summary	get_account (view: 'balance')
revoke_api_token	revoke_api_token (unchanged)
list_reference_data	list_reference_data (now 9 type values)
list_issue_definitions	list_reference_data (type: 'issue_definitions')
list_webhook_event_types	list_reference_data (type: 'webhook_event_types')
list_labels	search_catalog (entity: 'label')
list_artists	search_catalog (entity: 'artist')
list_writers	search_catalog (entity: 'writer')
list_publishers	search_catalog (entity: 'publisher')
list_releases	search_catalog (entity: 'release')
list_tracks	search_catalog (entity: 'track')
get_label	get_catalog_item (entity: 'label')
get_artist	get_catalog_item (entity: 'artist')
get_writer	get_catalog_item (entity: 'writer')
get_publisher	get_catalog_item (entity: 'publisher')
get_release	get_catalog_item (entity: 'release')
get_track	get_catalog_item (entity: 'track')
create_label	create_catalog_item (entity: 'label')
create_artist	create_catalog_item (entity: 'artist')
create_writer	create_catalog_item (entity: 'writer')
create_publisher	create_catalog_item (entity: 'publisher')
create_release	create_catalog_item (entity: 'release')
create_track	create_catalog_item (entity: 'track')
update_label	update_catalog_item (entity: 'label')
update_artist	update_catalog_item (entity: 'artist')
update_writer	update_catalog_item (entity: 'writer')
update_publisher	update_catalog_item (entity: 'publisher')
update_release	update_catalog_item (entity: 'release')
update_track	update_catalog_item (entity: 'track')
delete_label	delete_catalog_item (entity: 'label')
delete_artist	delete_catalog_item (entity: 'artist')
delete_writer	delete_catalog_item (entity: 'writer')
delete_publisher	delete_catalog_item (entity: 'publisher')
delete_release	delete_catalog_item (entity: 'release')
delete_track	delete_catalog_item (entity: 'track')
upload_label_image	upload_image (target: 'label_logo' | 'label_logo_dark' | 'label_background')
upload_artist_photo	upload_image (target: 'artist_photo')
get_track_file	get_asset (parent: 'track', mode: 'info', asset: 'stereo' | 'dolby' | 'lyrics')
get_release_file	get_asset (parent: 'release', mode: 'info', asset: 'square' | 'tall')
get_track_audio_download_url	get_asset (parent: 'track', mode: 'download_url', asset: 'audio_16' | 'audio_24' | 'audio_32' | 'audio_preview_full' | 'audio_preview_clip')
list_track_licenses	list_track_licenses (unchanged)
get_track_license	list_track_licenses (license_id: …)
list_review_issues	get_release_review (view: 'issues')
get_quality_report	get_release_review (view: 'quality_report')
list_stream_radar_flags	query_artificial_streaming (view: 'flags')
get_stream_radar_flag	query_artificial_streaming (view: 'flag_detail', flag_id: …)
list_artificial_streams	query_artificial_streaming (view: 'records')
get_artificial_fee_breakdown	query_artificial_streaming (view: 'fee_breakdown', period: 'YYYY-MM')
get_analytics	get_analytics (unchanged)
get_delivery_queue	get_delivery_queue (unchanged)
get_landing_config	get_landing_config (unchanged)
list_statements	query_financials (view: 'statements')
get_statement	query_financials (view: 'statement_detail', invoice_number: …)
list_transactions	query_financials (view: 'transactions')
get_royalties_breakdown	query_financials (view: 'royalty_breakdown', group_by: …)
download_statement_csv	download_statement (format: 'csv')
download_statement_invoice	download_statement (format: 'invoice_pdf')
list_webhooks	list_webhooks (view: 'config', the default)
get_webhook	list_webhooks (view: 'config', webhook_id: …)
get_webhook_logs	list_webhooks (view: 'logs', webhook_id: …)
create_webhook	manage_webhook (action: 'create')
update_webhook	manage_webhook (action: 'update')
delete_webhook	manage_webhook (action: 'delete')
test_webhook	manage_webhook (action: 'test')
rotate_webhook_secret	manage_webhook (action: 'rotate_secret')
validate_release	run_release_checks (check: 'validate')
refresh_quality_report	run_release_checks (check: 'refresh_quality_report')
update_landing_config	manage_release_links (action: 'update_landing_config', config: …)
create_release_short_url	manage_release_links (action: 'create_short_url')
add_review_issue_note	add_review_issue_note (unchanged)
upload_track_audio	upload_asset (target: 'track_stereo' | 'track_dolby' | 'track_lyrics')
upload_release_artwork	upload_asset (target: 'release_cover_art')
upload_release_asset	upload_asset (target: 'release_motion_square' | 'release_motion_tall')
delete_track_audio	delete_asset (target: 'track_stereo' | 'track_dolby' | 'track_lyrics')
delete_release_asset	delete_asset (target: 'release_motion_square' | 'release_motion_tall')
upload_track_license	manage_track_license (action: 'upload')
update_track_license	manage_track_license (action: 'update', track_license_id: …)
delete_track_license	manage_track_license (action: 'delete', track_license_id: …)
distribute_release	distribute_release (unchanged)
takedown_release	takedown_release (unchanged)
confirm_review	confirm_review (unchanged)
enable_beatport	enable_beatport (unchanged)

Safety model

The server has three gates. Each is fail-closed: a tool is only registered — and only callable — when its gate is armed.

• Reads — always on. Listing and fetching your catalog, analytics, statements, and so on.

• Safe writes (LABELGRID_ENABLE_WRITES, on by default) — reversible, draft-stage changes: creating and editing draft releases and tracks, labels, artists, writers, publishers, webhooks, landing pages, and notes. Set LABELGRID_ENABLE_WRITES=false (or LABELGRID_READ_ONLY=true) to turn these off.

• Full writes (LABELGRID_ENABLE_FULL_WRITES, off by default) — consequential, hard-to-reverse actions. To arm them you must set both:

  LABELGRID_ENABLE_FULL_WRITES=true
  LABELGRID_FULL_WRITES_ACK=I accept responsibility for AI-driven distribution actions
  

  The acknowledgment string must match exactly, or full writes stay off. When armed, the distribution toolset becomes available. These tools can:

  • upload finalized (immutable) track audio and release artwork,
  • upload, update, and delete track licenses,
  • distribute a release to stores — a final submission subject to your account's weekly limit,
  • take a release down from all stores,
  • confirm a held release into review,
  • request one-time Beatport onboarding for a label.

Leaving LABELGRID_ENABLE_FULL_WRITES unset is the safe default: your AI assistant can prepare and validate everything, but the irreversible submission stays a deliberate, opt-in step.

Rate limits & errors

Every tool returns either the API's JSON payload or a structured error — never a raw protocol failure — so your assistant can reason about what went wrong. The error shape is:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The submitted data was invalid.",
    "status": 422,
    "errors": { "title": ["The title field is required."] }
  }
}

Common codes: TOKEN_INVALID (401 — check your token), FORBIDDEN (403 — plan/permission or a locked field, with the server's code passed through), NOT_FOUND (404), VALIDATION_FAILED (422, with errors), RATE_LIMITED (429), SERVER_ERROR (5xx), NETWORK_ERROR, and FILE_NOT_FOUND / UPLOAD_FAILED for local file operations.

Rate limits. A 429 is surfaced with a retry_after_seconds field (from the API's Retry-After header). The server does not auto-retry — your client decides when to try again. Analytics is limited to roughly 60 requests per minute.

Contributing

Issues and pull requests are welcome. An API-coverage drift check runs in CI against a committed snapshot of the public API document and fails when the snapshot gains an endpoint this server does not expose (refresh the snapshot with node scripts/fetch-openapi.mjs). This repo uses:

• TypeScript (strict ESM), Node 20+, with @modelcontextprotocol/sdk and zod as the only runtime dependencies.
• Biome for lint + format (npm run lint).
• Vitest for tests (npm test).

Local workflow:

npm ci
npm run build        # tsc
npm test             # unit tests
npm run lint         # biome
npm run leak-guard   # repository hygiene scan
npm run gen-docs     # regenerate the tool table above (after build)

Every tool is a thin declaration — one HTTP call plus response shaping, no client-side business logic. Please keep it that way: validation and rules belong on the server. The tool table in this README is generated (npm run gen-docs); edit tool descriptions in src/tools/, not the table.

Legal notices

These disclosures are also surfaced at runtime: in the MCP instructions field your client receives on initialize, and on stderr at startup. The text below mirrors the runtime constants in src/legal.ts.

• Summary. This software is provided AS-IS, without warranty of any kind, express or implied. By using it you accept sole responsibility for your use of the LabelGrid API and for every action taken by any AI client or agent you connect to this server, including write operations against your LabelGrid account. Your use of the API through this server is governed by the LabelGrid API Terms of Service and Acceptable Use Policy. This server does not bypass server-side protections such as rate limits, plan entitlements, or terms enforcement. See LICENSE (MIT).
• Full writes. When full writes are armed: distribution submissions, takedowns, and immutable file uploads initiated by an AI agent have real, potentially irreversible consequences for your releases on streaming platforms and stores. By setting the LABELGRID_FULL_WRITES_ACK acknowledgment variable you accepted that all such actions are your sole responsibility.
• Data handling. This server transmits your LabelGrid catalogue and account data to the AI client you configure. Choosing that client, and disclosing that data flow where required, is your responsibility.

License

MIT © LabelGrid