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_MODULES 只加载您需要的内容：

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完成后填写。

高级工具（不需要API知识）

这些是大多数LLM应该使用的工具——它们包含了常见的多步骤工作流：

安全：确认门

所有突变都需要 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).

许可证

麻省理工学院