内容
# lexicon-mcp
TypeScript [MCP](https://modelcontextprotocol.io) 服务器，用于 [Lexicon DJ](https://www.lexicondj.com) **本地 API** — 从 Cursor、Claude、VS Code、Windsurf、Cline 或任何 MCP 客户端查询和更新您的库。
- API 文档：[developers/api](https://www.lexicondj.com/docs/developers/api)
- OpenAPI：[api-docs.yaml](https://www.lexicondj.com/developer/api-docs.yaml)
需要 **Lexicon** 运行并启用 **设置 → 集成 → 本地 API** （默认 `http://localhost:48624`）。
## 安装
无需安装软件包 — `npx -y` 按需下载并运行服务器。
将此服务器条目添加到您的 MCP 客户端（参见下文了解每个客户端存储其配置的位置）：
```json
"lexicon": {
"command": "npx",
"args": ["-y", "lexicon-mcp"]
}
```
编辑后重启客户端（或在支持的情况下重新加载 MCP 服务器）。`lexicon-mcp --help` 和 `lexicon-mcp -v` 在终端中工作；裸命令退出时会显示注释（MCP 使用标准输入/输出管道）。
### Cursor
**配置：** `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（项目）
```json
{
"mcpServers": {
"lexicon": {
"command": "npx",
"args": ["-y", "lexicon-mcp"]
}
}
}
```
### Claude Desktop
**配置：** `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS），`%APPDATA%\Claude\claude_desktop_config.json`（Windows），或 `~/.config/Claude/claude_desktop_config.json`（Linux）
与 Cursor 相同的 `mcpServers` 格式。完全退出并重新打开 Claude Desktop 后保存。
### Claude Code
**CLI** （项目范围，写入 `.mcp.json`）：
```bash
claude mcp add lexicon -- npx -y lexicon-mcp
```
**CLI with 环境变量：**
```bash
claude mcp add -e LEXICON_MCP_ALLOW_WRITES=1 lexicon -- npx -y lexicon-mcp
```
使用 `-s user` 获取所有项目的全局服务器。配置文件：`.mcp.json`（项目）或 `~/.claude.json`（用户）。
### VS Code / GitHub Copilot
**配置：** `.vscode/mcp.json`（工作区）或用户配置文件 `mcp.json`（运行 **MCP: 打开用户配置**）
VS Code 使用 `servers` 键和 `type` 字段：
```json
{
"servers": {
"lexicon": {
"type": "stdio",
"command": "npx",
"args": ["-y", "lexicon-mcp"]
}
}
}
```
### Windsurf
**配置：** `~/.codeium/windsurf/mcp_config.json`（macOS/Linux）或 `%USERPROFILE%\.codeium\windsurf\mcp_config.json`（Windows）
与 Cursor 相同的 `mcpServers` 格式。保存后重启 Windsurf。
### Cline
**配置：** Cline 侧边栏 → MCP 服务器 → 配置，或 `~/.cline/mcp.json`（CLI）。在 VS Code/Cursor 扩展中，设置存储在扩展的全局存储中，文件名为 `cline_mcp_settings.json`。
与 Cursor 相同的 `mcpServers` 格式。
### 环境
| 变量 | 默认值 | 目的 |
| --- | --- | --- |
| `LEXICON_HOST` | `localhost` | API 主机 |
| `LEXICON_PORT` | `48624` | API 端口 |
| `LEXICON_URL` | — | 完整基准 URL 重写 |
| `LEXICON_MCP_ALLOW_WRITES` | 关闭 | 设置为 `1` 以启用 PATCH/POST/DELETE |
将 `env` 块添加到服务器条目（或使用 `claude mcp add` 传递 `-e KEY=value`）：
**远程 Lexicon** — 另一台主机上的 API：
```json
"env": {
"LEXICON_HOST": "192.168.1.50",
"LEXICON_PORT": "48624"
}
```
**自定义 URL** — 使用完整基准 URL 重写主机/端口：
```json
"env": {
"LEXICON_URL": "http://studio.local:48624"
}
```
**启用写入** — 允许曲目更新、播放控制和其他变异 API 调用：
```json
"env": {
"LEXICON_MCP_ALLOW_WRITES": "1"
}
```
Cursor 中环境选项的示例：
```json
{
"mcpServers": {
"lexicon": {
"command": "npx",
"args": ["-y", "lexicon-mcp"],
"env": {
"LEXICON_MCP_ALLOW_WRITES": "1"
}
}
}
}
```
## 工具
### 读取（始终启用）
| 工具 | API |
| --- | --- |
| `lexicon_ping` | 健康检查 + 曲目计数 |
| `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` | 过滤后的传入待处理队列 |
| `lexicon_library_stats` | 复合统计 |
| `lexicon_list_playlists` | GET `/v1/playlists` |
| `lexicon_get_playlist` | GET `/v1/playlist` 或 `/v1/playlist-by-path` |
| `lexicon_get_playing` | GET `/v1/playing` |
| `lexicon_get_queue` | GET `/v1/queue` |
### 写入（需要 `LEXICON_MCP_ALLOW_WRITES=1`）
| 工具 | API |
| --- | --- |
| `lexicon_update_track` | PATCH `/v1/track` |
| `lexicon_control` | POST `/v1/control` |
| `lexicon_request` | 任意 `/v1/*` 方法 |
### 出口
| 工具 | 注释 |
| --- | --- |
| `lexicon_request` | 完整 API — 优先于已弃用的 `lexicon_raw_request` |
| `lexicon_raw_request` | 仅 GET（已弃用） |
## 开发
```bash
npm install
npm run build
npm test
npm link # 可选全局 bin
```
