AI导哈

音乐管理服务

一个基于MCP协议的服务，为AI代理提供对Lidarr音乐管理系统的完全控制功能，支持艺术家、专辑、发布等CRUD操作。

  • by abl030
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 abl030/lidarr-mcp

使用说明

Lidarr MCP服务器

MCP（模型上下文协议）服务器，使AI代理能够完全控制Lidarr音乐管理。自动生成自官方 Lidarr OpenAPI规范 （161条路径，236次操作）。

由于现有 mcp-arr-server 仅具有读取操作。这个有完整的CRUD操作——添加艺术家、监控专辑、抓取发布、管理质量配置文件、触发搜索和导入文件。所有的写入操作 花费了我们60%的代币 手动操作。

整个项目——生成器、服务器、测试套件和此README——由AI（Claude）构建，旨在供AI代理安装和使用。

安装

选项1：镍片（推荐）

# flake.nix
{
  inputs.lidarr-mcp.url = "github:abl030/lidarr-mcp";
}

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

无需安装即可快速测试：

LIDARR_URL=http://localhost:8686 LIDARR_API_KEY=your-key nix run github:abl030/lidarr-mcp

选项2:uv（非Nix）

git clone https://github.com/abl030/lidarr-mcp.git
cd lidarr-mcp
uv sync
uv run python -m generator    # produces generated/server.py

配置您的MCP客户端

克劳德代码：

# 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):

{
  "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 无论模块选择如何，始终都会注册。

示例配置：

# 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时，获取一个新的规范并重新运行：

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）

nix develop -c python -m pytest tests/ -v

集成测试（需要Lidarr）

# 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).

许可证

麻省理工学院

相关 MCP