Skip to main content
Glama
lexicon-mcp

lexicon-mcp

by Turbotailz

lexicon-mcp

TypeScript MCP server for the Lexicon DJ Local API — query and update your library from Cursor, Claude, VS Code, Windsurf, Cline, or any MCP client.

Requires Lexicon running with Settings → Integrations → Local API enabled (default http://localhost:48624).

Install

No package install required — npx -y downloads and runs the server on demand.

Add this server entry to your MCP client (see below for where each client stores its config):

"lexicon": {
  "command": "npx",
  "args": ["-y", "lexicon-mcp"]
}

Restart the client after editing (or reload MCP servers where supported). lexicon-mcp --help and lexicon-mcp -v work in a terminal; the bare command exits with a note (MCP uses stdio pipes).

Cursor

Config: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)

{
  "mcpServers": {
    "lexicon": {
      "command": "npx",
      "args": ["-y", "lexicon-mcp"]
    }
  }
}

Claude Desktop

Config: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows), or ~/.config/Claude/claude_desktop_config.json (Linux)

Same mcpServers format as Cursor. Fully quit and reopen Claude Desktop after saving.

Claude Code

CLI (project scope, writes to .mcp.json):

claude mcp add lexicon -- npx -y lexicon-mcp

CLI with environment variables:

claude mcp add -e LEXICON_MCP_ALLOW_WRITES=1 lexicon -- npx -y lexicon-mcp

Use -s user for a global server across all projects. Config files: .mcp.json (project) or ~/.claude.json (user).

VS Code / GitHub Copilot

Config: .vscode/mcp.json (workspace) or user-profile mcp.json (run MCP: Open User Configuration)

VS Code uses a servers key and a type field:

{
  "servers": {
    "lexicon": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "lexicon-mcp"]
    }
  }
}

Windsurf

Config: ~/.codeium/windsurf/mcp_config.json (macOS/Linux) or %USERPROFILE%\.codeium\windsurf\mcp_config.json (Windows)

Same mcpServers format as Cursor. Restart Windsurf after saving.

Cline

Config: Cline sidebar → MCP Servers → Configure, or ~/.cline/mcp.json (CLI). In VS Code/Cursor extensions, settings are stored under the extension's global storage as cline_mcp_settings.json.

Same mcpServers format as Cursor.

Environment

Variable

Default

Purpose

LEXICON_HOST

localhost

API host

LEXICON_PORT

48624

API port

LEXICON_URL

—

Full base URL override

LEXICON_MCP_ALLOW_WRITES

off

Set to 1 to enable PATCH/POST/DELETE

Add an env block to the server entry (or pass -e KEY=value with claude mcp add):

Remote Lexicon — API on another host:

"env": {
  "LEXICON_HOST": "192.168.1.50",
  "LEXICON_PORT": "48624"
}

Custom URL — override host/port with a full base URL:

"env": {
  "LEXICON_URL": "http://studio.local:48624"
}

Writes enabled — allow track updates, playback control, and other mutating API calls:

"env": {
  "LEXICON_MCP_ALLOW_WRITES": "1"
}

Example with environment options in Cursor:

{
  "mcpServers": {
    "lexicon": {
      "command": "npx",
      "args": ["-y", "lexicon-mcp"],
      "env": {
        "LEXICON_MCP_ALLOW_WRITES": "1"
      }
    }
  }
}

Related MCP server: YotoMCP Local

Tools

Read (always on)

Tool

API

lexicon_ping

health + track count

lexicon_list_tags

GET /v1/tags

lexicon_list_tracks

GET /v1/tracks

lexicon_get_track

GET /v1/track

lexicon_search_tracks

GET /v1/search/tracks

lexicon_list_incoming

filtered incoming backlog

lexicon_library_stats

composed stats

lexicon_list_playlists

GET /v1/playlists

lexicon_get_playlist

GET /v1/playlist or /v1/playlist-by-path

lexicon_get_playing

GET /v1/playing

lexicon_get_queue

GET /v1/queue

Write (requires LEXICON_MCP_ALLOW_WRITES=1)

Tool

API

lexicon_update_track

PATCH /v1/track

lexicon_control

POST /v1/control

lexicon_request

any /v1/* method

Escape hatch

Tool

Notes

lexicon_request

Full API — prefer this over deprecated lexicon_raw_request

lexicon_raw_request

GET only (deprecated)

Development

npm install
npm run build
npm test
npm link   # optional global bin

Available Tools

15 tools
lexicon_controlC

Run a Lexicon control action (e.g. Incoming_SelectedDone, Application_Tags_AddShortcut). Requires LEXICON_MCP_ALLOW_WRITES=1.

Inputs: action (required), parameters.

lexicon_get_playingA

Get the currently playing track and player progress.

Inputs: no named parameters.

lexicon_get_playlistA

Get one playlist by ID or by path (path survives library re-import).

Inputs: id, path, type.

lexicon_get_queueA

Get the player queue (excluding the current track).

Inputs: no named parameters.

lexicon_get_trackA

Get one track by ID (full payload: tags, cuepoints, tempomarkers, etc.).

Inputs: id (required).

lexicon_library_statsC

Summarize library health: totals, incoming, tracks without a Genre tag.

Inputs: sampleLimit.

lexicon_list_incomingC

List tracks in the Incoming queue or under DJ-incoming watch folder.

Inputs: limit.

lexicon_list_playlistsA

List playlist tree from Lexicon (folders, playlists, smart playlists).

Inputs: no named parameters.

lexicon_list_tagsA

List My Tag categories and tags from Lexicon (Genre, Vibe, Event, Role, etc.).

Inputs: no named parameters.

lexicon_list_tracksA

List tracks from the Lexicon library (paginated, newest first).

Inputs: limit, offset.

lexicon_pingA

Check Lexicon Local API is reachable (Lexicon app must be running with API enabled under Settings → Integrations).

Inputs: no named parameters.

lexicon_raw_requestB

Deprecated: use lexicon_request with method GET. Call any Lexicon /v1 path with JSON body.

Inputs: path (required), body.

lexicon_requestB

Call any Lexicon /v1 endpoint (GET, PATCH, POST, DELETE). See https://www.lexicondj.com/developer/api-docs.yaml. Non-GET requires LEXICON_MCP_ALLOW_WRITES=1.

Inputs: path (required), method (required), body.

lexicon_search_tracksA

Search tracks using Lexicon filters. Examples:

  • { "tags": "irh" } — has event tag irh

  • { "tags": "!house" } — missing house genre tag

  • { "tags": "~house, pop" } — has house AND pop

  • { "artist": "Daft Punk" }

  • { "location": "DJ-incoming" }

Inputs: filter (required).

lexicon_update_trackA

Update one track (tags, metadata, cuepoints, incoming flag). Requires LEXICON_MCP_ALLOW_WRITES=1.

Inputs: id (required), edits (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have clear distinct purposes (ping, list, get, update, search, control, player status). However, lexicon_request and lexicon_raw_request are redundant, and lexicon_control is a catch-all that could overlap with other specific actions.

    Naming Consistency5/5

    All tools follow a consistent 'lexicon_verb_noun' pattern using snake_case. The deprecated raw_request is slightly irregular but clearly marked.

    Tool Count5/5

    15 tools cover a comprehensive set of operations for a DJ library management API without being overwhelming or too sparse.

    Completeness4/5

    Core operations for tracks, playlists, library stats, and player state are covered. A generic 'request' endpoint fills gaps, but explicit create/delete for playlists is missing.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP-aware AI clients to read, query, and modify a Lexicon DJ library through structured tool calls, including searching tracks, managing tags, and curating playlists or smartlists.
      13
      MIT
    • F
      license
      A
      quality
      B
      maintenance
      Enables secure local management of Yoto cards, devices, and audio uploads through the official Yoto API, using OAuth PKCE authentication with read-only tools enabled by default and opt-in writes.
      7
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects AI assistants to a local music library for full-text search and filtering of tracks, albums, artists, genres, composers, and lyrics, plus listening analytics and metadata hygiene audits. Also lets users generate and populate playlists and control playback (play, pause, seek, volume) in a running player instance.
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Enables AI assistants to query and manage a local Engine DJ library on macOS, including searching tracks by BPM, key, genre, or comments, auditing duplicates and missing files, reading cues and beatgrids, and building playlists or fixing tags when write access is enabled.
      9
      109 npm
      1
      MIT