Lexicon

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.

• API docs: developers/api
• OpenAPI: api-docs.yaml

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"
      }
    }
  }
}

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