Lidarr MCP服务器
MCP(模型上下文协议)服务器,使AI代理能够完全控制Lidarr音乐管理。自动生成自官方 Lidarr OpenAPI规范 (161条路径,236次操作)。
由于现有 mcp-arr-server 仅具有读取操作。这个有完整的CRUD操作——添加艺术家、监控专辑、抓取发布、管理质量配置文件、触发搜索和导入文件。所有的写入操作 花费了我们60%的代币 手动操作。
整个项目——生成器、服务器、测试套件和此README——由AI(Claude)构建,旨在供AI代理安装和使用。
安装
选项1:镍片(推荐)```nix
flake.nix
{
inputs.lidarr-mcp.url = "github:abl030/lidarr-mcp";
}
``````nix
Use the package
environment.systemPackages = [ inputs.lidarr-mcp.packages.${pkgs.system}.default ];
Or in an MCP server config
{
command = "${inputs.lidarr-mcp.packages.${pkgs.system}.default}/bin/lidarr-mcp";
env = {
LIDARR_URL = "http://localhost:8686";
LIDARR_API_KEY = "your-api-key";
};
}
无需安装即可快速测试:```bash
LIDARR_URL=http://localhost:8686 LIDARR_API_KEY=your-key nix run github:abl030/lidarr-mcp
选项2:uv(非Nix)```bash
git clone https://github.com/abl030/lidarr-mcp.git
cd lidarr-mcp
uv sync
uv run python -m generator # produces generated/server.py
### 配置您的MCP客户端
**克劳德代码:**```bash
# Nix
claude mcp add lidarr -- \
env LIDARR_URL=http://YOUR_LIDARR_HOST:8686 \
LIDARR_API_KEY=YOUR_API_KEY \
lidarr-mcp
# Non-Nix
claude mcp add lidarr -- \
env LIDARR_URL=http://YOUR_LIDARR_HOST:8686 \
LIDARR_API_KEY=YOUR_API_KEY \
uv run --directory /path/to/lidarr-mcp fastmcp run generated/server.py
克劳德桌面 (claude_desktop_config.json):```json
{
"mcpServers": {
"lidarr": {
"command": "lidarr-mcp",
"env": {
"LIDARR_URL": "http://YOUR_LIDARR_HOST:8686",
"LIDARR_API_KEY": "YOUR_API_KEY",
"LIDARR_MODULES": "artist,album,queue,release,command,quality,system"
}
}
}
}
### 环境变量
|变量|默认值|描述|
|----------|---------|-------------|
| `LIDARR_URL` | `http://localhost:8686` |Lidarr基本URL|
| `LIDARR_API_KEY` | *(必填)* |API密钥(“设置”>“常规”>“安全性”)|
| `LIDARR_MODULES` | *(所有模块)* |以逗号分隔的要启用的模块列表|
| `LIDARR_READ_ONLY` | `false` |删除所有突变工具(POST/PUT/DELETE)|
### 模块过滤
默认情况下,所有工具都已注册。集 `LIDARR_MODULES` 只加载您需要的内容:
|模块|它涵盖了什么|
|--------|----------------|
| `artist` |艺术家CRUD、查找、编辑器、批量操作|
| `album` |相册CRUD、查找、监控、相册工作室|
| `track` |跟踪列表和文件管理|
| `release` |释放搜索和抓取|
| `queue` |下载队列管理|
| `command` |触发搜索、重新扫描、导入、重命名|
| `quality` |质量配置文件和自定义格式|
| `wanted` |缺少/截断相册|
| `history` |导入/抓取历史记录|
| `calendar` |即将发布|
| `indexer` |索引器配置|
| `downloadclient` |下载客户端管理|
| `importlist` |进口清单管理|
| `system` |运行状况、备份、磁盘空间、日志、标签、根文件夹|
| `config` |主机、命名、媒体管理设置|
`lidarr_get_overview`, `lidarr_search_tools`,以及 `lidarr_report_issue` 无论模块选择如何,始终都会注册。
**示例配置:**```bash
# Music management (~core tools)
LIDARR_MODULES=artist,album,release,queue,command,quality,wanted
# Read-only monitoring
LIDARR_MODULES=artist,album,queue,wanted,history
LIDARR_READ_ONLY=true
# Full control
# (default — all modules enabled)
所得
TODO:工具计数将在生成器Sprint 1完成后填写。
| 类别 | 示例 |
|---|---|
| 艺术家 | 添加、更新、删除、查找、批量编辑、按MusicBrainz ID搜索 |
| 专辑 | CRUD、监视器/非监视器、录音室 |
| 发布 | 搜索专辑版本,获取特定版本 |
| 队列 | 列出、删除、批量删除下载 |
| 命令 | 相册搜索、ArtistSearch、重新扫描艺术家、刷新艺术家、手动导入、重命名 |
| 质量 | 配置文件CRUD,自定义格式CRUD |
| 通缉 | 缺少相册,未满足截止日期 |
| 历史 | 导入/抓取历史记录,标记失败 |
| 日历 | 按日期范围列出的即将发布的版本 |
| 系统 | 运行状况、磁盘空间、备份、标签、根文件夹、日志 |
高级工具(不需要API知识)
这些是大多数LLM应该使用的工具——它们包含了常见的多步骤工作流:
| 工具 | 说明 |
|---|---|
lidarr_get_overview |
系统摘要:运行状况、磁盘空间、队列、需要、艺术家数量 |
lidarr_search_tools |
在所有工具名称/描述中进行关键字搜索 |
lidarr_report_issue |
生成结构化错误报告 |
安全:确认门
所有突变都需要 confirm=True。没有它,你会得到一个模拟预览:```
Preview only — nothing changes
lidarr_add_artist(term="Linkin Park", quality_profile_id=1, root_folder_path="/music")
Actually adds the artist
lidarr_add_artist(term="Linkin Park", quality_profile_id=1, root_folder_path="/music", confirm=True)
### 列表工具筛选
全部 `lidarr_list_*` 工具支持可选参数:
- **`fields`** --要返回的逗号分隔的字段名(例如。 `"id,artistName,monitored"`)
- **`query`** --用于行过滤的键值对(例如。 `{"monitored": true}`)
### 错误报告
每个工具的文档字符串都促使人工智能消费者调用 `lidarr_report_issue` 意外错误。此工具编写了一个即贴即用的 `gh issue create` 具有结构化上下文的命令。
## 运作原理
蟒蛇 **发电机** 读取Lidarr OpenAPI 3.0.4规范(161条路径,236次操作),并通过Jinja2模板生成MCP服务器。当Lidarr更新他们的API时,获取一个新的规范并重新运行:```bash
nix develop -c python -m generator # regenerates generated/server.py
生成的服务器使用FastMCP和单个 LidarrClient 类(httpx+neneneba API密钥验证通过 X-Api-Key 头球每个API操作一个异步工具函数。切勿手动编辑生成的输出,而应修复生成器。
建筑```
spec/openapi.json # Lidarr OpenAPI 3.0.4 spec (input, 161 paths)
generator/ # Python generator
main.py # Entry point: python -m generator
loader.py # Load and parse the OpenAPI spec
naming.py # Convert operationIds to tool names
schema_parser.py # Extract parameter types from schemas
context_builder.py # Build template context, assign modules
codegen.py # Render templates and write output
templates/
server.py.j2 # FastMCP server template
generated/
server.py # The MCP server (never hand-edit)
tests/ # Unit + integration tests
research/ # Best practices, API notes
## 测试
### 单元测试(无需Lidarr)```bash
nix develop -c python -m pytest tests/ -v
集成测试(需要Lidarr)```bash
Start Lidarr in Docker
docker compose -f docker/docker-compose.yml up -d
Wait for ready
bash docker/wait-for-ready.sh
Run integration tests
nix develop -c python -m pytest tests/test_integration.py -v --integration
Tear down
docker compose -f docker/docker-compose.yml down
```
Sprint计划
Sprint 1:发电机核心
- []OpenAPI规范加载器(
loader.py)--解析路径、操作、模式 - []命名约定(
naming.py) —operationId到lidarr_{verb}_{resource} - []模式解析器(
schema_parser.py)--提取参数类型,句柄$ref,allOf - []上下文生成器(
context_builder.py)--分配模块,构建模板上下文 - []代码生成器(
codegen.py)--通过Jinja2渲染server.py - []服务器模板(
server.py.j2)——配备LidarrClient、模块门控、确认门控的FastMCP服务器 - []生成并验证刀具数量是否符合规格
Sprint 2:质量和正确性
- []应用MCP最佳实践(参见
research/mcp-server-best-practices.md) - 对大整数(>=2^53)进行消毒
- 从请求参数中排除只读字段
- 参数描述中的枚举值
- 条件必填字段降级为可选字段
- 从描述中删除HTML
- PATCH默认为无
- []列出工具增强功能:
fields,query参数,文档字符串中的“已知字段” - []高级工具:
lidarr_get_overview,lidarr_search_tools,lidarr_report_issue - []单元测试:命名、模块、列表工具
Sprint 3:Nix封装和集成
- [ ]
flake.nix使用包+devShell - [ ]
pyproject.toml具有紫外线依赖性 - []Docker compose用于集成测试
- []针对实时Lidarr的集成测试
Sprint 4:LLM测试(银行测试员)
- []任务配置和自动生成的任务文件
- []在Docker中对Lidarr运行银行测试
- []分析覆盖率,修复首次尝试失败
- []测试反馈对文档字符串的改进
Sprint 5:文档和发布
- []在README中填写工具计数
- []添加银行测试器覆盖表
- []连接到nixoconfig
.mcp.json - []替换
mcp-arr-server包装器
这个项目是人工智能生成的
这个存储库中的每个文件都是由Claude(Anthropic)编写的。生成器、模板、测试套件、这个README——所有这些。专为AI对AI使用而设计:AI生成服务器,AI代理使用它来管理Lidarr音乐库。
人类也受到欢迎。
依赖项
Nix用户:
nix run github:abl030/lidarr-mcp --一切捆绑。
非Nix用户: Python 3.11+, 紫外线、fastmcp、httpx、jinja2(由安装者安装) uv sync).
许可证
麻省理工学院
