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.

• 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