Content
# lexicon-mcp
TypeScript [MCP](https://modelcontextprotocol.io) server for the [Lexicon DJ](https://www.lexicondj.com) **Local API** — query and update your library from Cursor, Claude, VS Code, Windsurf, Cline, or any MCP client.
- API docs: [developers/api](https://www.lexicondj.com/docs/developers/api)
- OpenAPI: [api-docs.yaml](https://www.lexicondj.com/developer/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):
```json
"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)
```json
{
"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`):
```bash
claude mcp add lexicon -- npx -y lexicon-mcp
```
**CLI with environment variables:**
```bash
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:
```json
{
"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:
```json
"env": {
"LEXICON_HOST": "192.168.1.50",
"LEXICON_PORT": "48624"
}
```
**Custom URL** — override host/port with a full base URL:
```json
"env": {
"LEXICON_URL": "http://studio.local:48624"
}
```
**Writes enabled** — allow track updates, playback control, and other mutating API calls:
```json
"env": {
"LEXICON_MCP_ALLOW_WRITES": "1"
}
```
Example with environment options in Cursor:
```json
{
"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
```bash
npm install
npm run build
npm test
npm link # optional global bin
```
