logicmonitor

LogicMonitor MCP 服务

用于集成 LogicMonitor REST API v3 的 Model Context Protocol（MCP）服务。通过 306 个结构化工具、15 个工作流提示词和 26 个资源，让 AI 助手能够与 LogicMonitor 监控数据交互。可选集成包括：用于 Granite TTM 预测和自然语言摘要的 IBM watsonx.ai、适用于任何提供商的 Terraform IaC，以及作为本地 Granite 模型回退方案的 HuggingFace。

兼容任何 MCP 客户端：Claude Desktop、Claude Code、Cursor、Continue、Cline 等。

快速开始

1. 获取 LogicMonitor Bearer Token：

• 登录 LogicMonitor 门户
• 前往 Settings → Users and Roles → API Tokens
• 创建新的仅 API 用户，或为现有用户添加令牌
• 复制 Bearer Token

2. 配置 MCP 客户端：

适用于 Claude Code（CLI）：

claude mcp add logicmonitor \
  -e LM_PORTAL=yourcompany.logicmonitor.com \
  -e LM_BEARER_TOKEN=<your-bearer-token> \
  -- uvx --from lm-mcp lm-mcp-server

集成 IBM watsonx.ai（可选——增加 Granite TTM 预测和自然语言摘要）：

claude mcp add logicmonitor \
  -e LM_PORTAL=yourcompany.logicmonitor.com \
  -e LM_BEARER_TOKEN=<your-bearer-token> \
  -e WATSONX_API_KEY=<your-ibm-cloud-api-key> \
  -e WATSONX_URL=https://us-south.ml.cloud.ibm.com \
  -e WATSONX_PROJECT_ID=your-watsonx-project-id \
  -- uvx --from "lm-mcp[ibm]" lm-mcp-server

使用 Terraform IaC（可选——增加 terraform plan/apply/generate 工具）：

claude mcp add logicmonitor \
  -e LM_PORTAL=yourcompany.logicmonitor.com \
  -e LM_BEARER_TOKEN=<your-bearer-token> \
  -e TF_WORKSPACE_DIR=/path/to/terraform/workspaces \
  -- uvx --from lm-mcp lm-mcp-server

使用 HuggingFace 本地模型（可选——本地 Granite TTM 和自然语言摘要，无需云 API）：

claude mcp add logicmonitor \
  -e LM_PORTAL=yourcompany.logicmonitor.com \
  -e LM_BEARER_TOKEN=<your-bearer-token> \
  -- uvx --from "lm-mcp[huggingface]" lm-mcp-server

对于 Claude Desktop，请添加到配置文件中（见下方的 MCP 客户端配置）。

3. 验证是否正常运行：

claude mcp list

你应该会看到：logicmonitor: uvx --from lm-mcp lm-mcp-server - ✓ Connected

4. 使用提示词进行测试：

"Show me all critical alerts in LogicMonitor"

v4.2.1 新增内容

这是一个修复版本。LMv1 门户现已恢复认证，包括写入操作：签名遵循 LogicMonitor 记录的规范，并覆盖实际发送的确切字节。工具错误会通过 isError: true 传递给客户端，并作为失败记录进行审计；每个工具均可按自身架构调用；stdio 在所有配置下均可启动；/readyz 不再调用门户。现在，发布版本必须通过 Python 3.11 至 3.13 的测试套件；容器使用哈希校验从 uv.lock 安装依赖、使用固定摘要的基础镜像，并采用固定的非 root UID。

v4.2.0

v4.2.0 新增内容

增强了多门户模式。现在，单个服务可以同时服务多个客户门户，并在运行时通过 list_portals、use_portal、current_portal 和 reload_portals 选择当前门户——只需在 MCP 客户端中配置一项，而不必为每个门户分别配置一个服务（并粘贴一个令牌）。凭证存储在使用 age 加密的保险库中；除非保险库记录另有说明，否则每个门户均为只读；此模式有意限定为仅支持 stdio：服务拒绝在共享 HTTP 传输上启动。此版本还全面更新了依赖项，清除了锁文件中的 53 条 Dependabot 警报。

v4.1.0

v4.1.0 新增内容

原生 OTLP 指标现已推出。LogicMonitor 的新 OTLP Metrics 功能（由功能标志控制，基于 Prometheus）首阶段仅提供一个 UI 入口（仪表板 Advanced Metrics Widget），尚无 Metrics Explorer；这四个工具率先提供了对这些数据的编程访问：用于发现的 get_otlp_metric_names、get_otlp_metric_labels 和 get_otlp_label_values，以及用于执行完整 PromQL 范围查询并返回时间序列矩阵的 query_otlp_metrics。这四个工具均已在启用功能标志、接入真实 OTel 收集器（Kubernetes cAdvisor 和应用指标）的门户上完成实时验证；对于未启用该功能的门户响应，它们会转换为清晰的可用性提示；对于大型矩阵响应，它们会通过等间隔下采样进行限制，使其更适合大模型处理。

## v4.0.0 新增内容

重大更新。 现在每个工具都封装了经验证确实存在的端点，并通过实时门户进行了验证。自推出以来一直调用不存在的 API 路径的 6 个工具已被移除（get_cloud_cost_accounts、get_cost_summary、get_resource_cost、get_remediation_status、get_remediation_history、get_batchjob_history）；成本建议工具改用可用的 /cost-optimization API；Service Insight 工具现在查询真实的 Service Insight 对象（deviceType 6 设备和 BizService 组），而非旧版 v1 websites API。Automated Diagnostics & Remediation 功能已完整推出：get_diagnostic_remediation_assignments 和 get_diagnostic_remediation_results（结构化执行记录，包含脚本输出，取代审计日志抓取）、execute_diagnostic、诊断和修复来源的完整 CRUD 及导入/导出功能，以及新的 action chain / action rule 命名空间（共 11 个工具，包括 set_action_rule_status 开关）。update_logicmodule 新增两种来源类型，其应用模式现在会实际生效（此前会触发其子工具自身的确认保护）。run_report 执行结果可通过 get_report_execution 轮询，get_alert_details 可获取完整消息正文，报表列表工具也能查看 NextGen 报表。

完整的版本历史（包括 v3.9.x 及更早版本）请参阅 CHANGELOG.md。v3.8.0 网络智能工具的专属参考文档：documentation/networking-intelligence.md。

功能

306 个工具，全面覆盖 LogicMonitor API（277 个 LM + 18 个 AAP + 10 个 Terraform + 1 个 watsonx）：

核心监控

• 告警管理：查询、确认、批量确认、添加备注、查看规则
• 设备管理：完整 CRUD——列出、创建、更新、删除设备和组
• 指标与数据：查询数据源、实例、指标数据和图表。支持手动数据源实例的实例 CRUD。
• 仪表板管理：支持仪表板、小组件和组的完整 CRUD
• SDT 管理：创建、列出、批量创建/删除计划停机时间
• Collector 管理：列出 Collector 和 Collector 组

扩展功能

• 网站监控：支持合成检查和网站组的完整 CRUD
• 报表管理：列出、查看、运行报表，管理计划
• 升级管理：支持升级链和接收者组的完整 CRUD
• 告警规则：支持告警路由规则的完整 CRUD
• 用户与角色管理：查看用户、角色、访问组和 API 令牌
• 运维管理：审计日志、运维备注、登录/变更审计
• 自动化诊断与修复：分配来源解析、包含脚本输出的结构化执行结果、诊断/修复来源 CRUD、手动执行、action chain 和规则
• 原生 OTLP 指标（预览版）：针对受功能标志控制的 OTLP 指标存储，提供指标和标签发现以及 PromQL 范围查询

AI 分析工具

服务端智能功能，可将原始监控数据转化为可执行的洞察：

• 告警关联：按设备、数据源和时间接近程度自动聚类相关告警——通过单个聚合视图取代数十次手动 API 调用
• 告警统计：按严重性汇总告警数量，统计排名前 10 的设备和数据源，并提供按时间分桶的分布数据以分析趋势
• 指标异常检测：采用多种方法（z-score、IQR、MAD）进行异常检测，并根据数据分布自动选择方法
• 指标基线：保存指标行为的基线快照，再将当前性能与基线进行比较，以检测偏移
• 计划分析：提供 HTTP API 端点，以便从外部计划程序和 Webhook 触发分析工作流（告警关联、RCA、流量发送方排名、运行状况检查）

ML/统计分析工具

用于容量规划、趋势分析和运维评分的纯 Python 统计方法：

• 指标预测：线性回归、Holt-Winters 三重指数平滑，以及 IBM Granite TTM（通过 watsonx.ai，可选），支持自动选择、置信区间和阈值超限预测
• 指标相关性：计算多个指标序列的 Pearson 相关矩阵，并突出显示强相关性
• 错误预算跟踪：基于 SLO 计算错误预算，并提供消耗速率、预计耗尽时间和状态分类
• 变更点检测：使用 CUSUM 算法识别状态转变和均值变化
• 告警噪声评分：通过 Shannon 熵和抖动检测量化告警噪声（0-100），并提供调优建议
• 季节性检测：基于自相关，在标准间隔检测周期性并识别高峰时段
• 可用性计算：根据告警历史计算 SLA 式正常运行时间百分比，并提供 MTTR、事件数量和按设备细分的数据
• 影响范围分析：基于拓扑，为设备故障场景计算下游影响评分
• 变更关联：交叉参考告警激增与审计/变更日志，以识别由变更引发的事件
• 趋势分类：将指标归类为稳定、上升、下降、周期性或波动
• 设备健康评分：使用 z-score 分析和可配置权重，计算多指标综合健康评分（0-100）

组合工作流工具

将多个子工具组合为一次调用的多步骤分析工具。每个工具都支持 detail_level（"summary" 或 "full"），可选的 summarize=true 可通过 IBM Granite 生成通俗易懂的自然语言摘要（需要 watsonx.ai），并能妥善处理子工具故障，返回部分结果。

• 分诊：关联活动告警、评估噪声、分析影响范围，并交叉参考近期变更
• 健康检查：设备健康评分、监控覆盖率、异常检测、活动告警和 30 天可用性
• 容量规划：按数据源进行预测、趋势分类、季节性检测和变更点分析
• 门户概览：告警统计、采集器健康状况、活动 SDT、告警集群、噪声评估和停机设备
• 诊断：告警详情、设备上下文、相关性、影响范围、健康评分和根因分析
• 更新 LogicModule（安全部分更新）：update_logicmodule(type, id, changes, mode) 导出当前完整定义，深度合并你的 changes，验证必填字段，并返回试运行差异（默认），或应用合并结果。可防止整体替换导致内容被清空；此前两起事件中，生产环境的 Groovy 脚本就因此被清空。支持 configsource、datasource、eventsource、logsource、propertysource、topologysource。
• 搜索工具：按名称和描述对所有工具进行关键词搜索，并支持按类别筛选

APM 链路追踪工具

适用于 LogicMonitor APM（应用性能监控）的服务发现和 RED 指标：

• 服务发现：列出所有被追踪的服务，检查单个服务的详情和属性
• 操作列表：发现每个服务中受监控的端点/路由
• RED 指标：提供服务级和单个操作级的持续时间、错误计数和操作计数
• 告警集成：查看任意被追踪服务的活动告警
• 属性检查：查看 OTel 属性、命名空间信息和自动发现的元数据

Ansible Automation Platform 集成

提供 18 个工具，通过 Ansible Automation Platform（AAP）实现由可观测性驱动的修复。将 LogicMonitor 告警连接到自动化修复 playbook。

• 作业模板：列出、检查和启动作业模板，并设置额外变量和主机限制
• 作业执行：启动作业、检查状态、查看输出、取消或重新启动运行
• 工作流：启动工作流模板，监控多步骤自动化序列
• 清单与主机：列出清单，检查主机以进行有针对性的修复
• 项目与凭据：浏览可用项目和凭据（不会公开密钥）
• 写入保护：launch_job、launch_workflow、cancel_job、relaunch_job 需要设置 LM_ENABLE_WRITE_OPERATIONS=true
• Jinja2 安全性：验证所有 extra_vars 输入，以防止模板注入

AAP 工具为可选项——仅当配置了 AWX_URL 和 AWX_TOKEN 时才会显示。修复模板请参阅示例 Playbook。

IBM watsonx.ai 集成

通过 watsonx.ai 使用 IBM Granite 基础模型提供可选的 AI 增强功能。需要 IBM Cloud 账户和 watsonx.ai 项目（支持 Lite/免费套餐）。

• Granite TTM 预测：使用 IBM Granite Tiny Time Mixer（TTM）进行机器学习驱动的时间序列预测。在 forecast_metric 中使用 method="ttm"，即可生成 96 步预测，检测季节性和非线性模式。需要 512 个以上的数据点。数据不足时会自动回退到统计方法。
• Granite 自然语言摘要：为复合工作流工具（triage、diagnose、health_check、capacity_plan、portal_overview）生成通俗易懂的交接摘要。传入 summarize=true，即可在结构化输出中附加 IBM Granite 生成的分析摘要。
• watsonx_summarize：独立工具，可接收任意 JSON 数据并通过 Granite 4.0 生成简洁的自然语言摘要。适合汇总任何 MCP 工具的输出。

watsonx 工具为可选项——仅当配置了 WATSONX_API_KEY 和 WATSONX_PROJECT_ID 时才会显示。安装 lm-mcp[ibm] 以包含 IBM SDK 依赖项。

设置：

1. 在 cloud.ibm.com 创建免费的 IBM Cloud 账户
2. 在 IBM Cloud 目录中开通 watsonx.ai Runtime（Lite 套餐，免费）
3. 创建 watsonx.ai 项目，并关联 Runtime 实例
4. 在 cloud.ibm.com/iam/apikeys 生成 IBM Cloud API 密钥
5. 使用 WATSONX_API_KEY、WATSONX_URL 和 WATSONX_PROJECT_ID 配置 MCP 服务

Terraform 集成

11 个工具，支持使用任意 Terraform 提供商执行基础设施即代码工作流。AI Agent 可以编写 HCL、使用预制脚本，或对现有 LM 资源进行逆向工程。

• terraform_init：初始化工作区并下载提供商（需要写入权限）
• terraform_validate：检查 HCL 配置语法
• terraform_plan：预览变更并输出结构化 JSON（需要写入权限：提供商和数据源会调用实时 API）
• terraform_apply：应用变更（需通过三重门控：写入权限 + 配置标志 + 确认参数）
• terraform_destroy：销毁基础设施（同样需通过三重门控）
• terraform_import：将现有资源导入 Terraform 状态
• terraform_state_list / terraform_state_show：检查当前状态
• terraform_output：查看 Terraform 输出
• terraform_write_config：将 HCL 文件写入工作区目录
• terraform_generate：使用 logicmonitor/logicmonitor 提供商将现有 LM 门户资源导出为 HCL

Terraform 工具为可选工具——只有在配置了 TF_WORKSPACE_DIR 时才会显示。需要单独安装 terraform CLI。

terraform 子进程只会从服务的环境中继承 PATH、HOME、TMPDIR、TF_*、代理设置（HTTP_PROXY、HTTPS_PROXY、NO_PROXY 及其小写形式）和 CA 设置（SSL_CERT_FILE、SSL_CERT_DIR），因此，服务和云凭据（例如 LM_BEARER_TOKEN 或 AWS_SECRET_ACCESS_KEY）不会传递给提供商或数据源代码。logicmonitor 提供商会从服务的 LMv1 配置中获取 LM_API_ID、LM_API_KEY 和 LM_COMPANY（以及对应的 TF_VAR_lm_* 形式）。其他提供商通过 HCL 传递给它们的 TF_VAR_* 变量或 HOME 下的文件（例如 ~/.aws/credentials）获取凭据。后端块无法读取变量，因此后端凭据需从 HOME 下的文件或 terraform_init 的 backend_config 键（例如 profile、access_key、sas_token）获取。

var_file 和本地后端 path（包括符号链接）解析后必须位于工作区内。terraform_init 的 backend_config 接受包含本地、s3 或 azurerm 后端键的对象，并会按名称拒绝端点和代理覆盖。超过 TF_TIMEOUT 的命令会收到 SIGINT，并有 30 秒时间持久化状态和释放锁，之后才会被终止；超时的 apply 或 destroy 会报告锁可能仍被占用，且状态可能不完整。

三种入口：

1. Agent 编写：AI 根据自然语言生成 HCL，写入工作区，规划并应用
2. 预制脚本：将 TF_WORKSPACE_DIR 指向现有 .tf 文件，由 Agent 操作这些文件
3. 逆向工程：terraform_generate 将 LM 资源导出为 HCL，然后导入状态

HuggingFace 本地回退

未配置 watsonx.ai API 凭据时，TTM 预测和 NL 摘要会自动通过 HuggingFace transformers 回退到本地 Granite 模型。使用 lm-mcp[huggingface] 安装。

优先级顺序： watsonx.ai API（远程）> HuggingFace 本地 > 统计/线性方法

• TTM 模型：ibm-granite/granite-timeseries-ttm-r2（512 上下文，96 预测）
• LLM 模型：ibm-granite/granite-3.3-2b-instruct（2B 参数，可在 CPU 上运行）
• 模型会在首次推理调用时延迟加载（初始下载量：TTM 约 500MB，LLM 约 4GB）
• 与 WatsonxClient 接口相同——所有现有 watsonx 工具均可使用任一后端

LogicModules

• 数据源：查询并导出数据源定义
• 配置源：查询定义、从配置归档中获取设备配置数据、查看差异、触发按需采集，并审计变更历史
• 事件源：查询并导出事件检测模块
• 属性源：查询、创建并导出属性采集模块
• 拓扑源：查询并导出拓扑映射模块
• 日志源：查询并导出日志采集模块
• 导入支持：从 JSON 定义导入 LogicModules

高级功能

• 成本优化：成本建议、建议类别、空闲资源（LM Envision）
• 网络拓扑：设备邻居、接口、流量、连接
• 批处理作业：查看和管理批处理作业执行历史
• 日志/指标摄取：通过 LMv1 身份验证推送日志和指标

MCP 协议功能

• 资源：26 个用于 API 参考的架构/枚举/筛选器/指南资源
• 提示词：15 个工作流模板（事件分流、RCA、容量预测、修复执行等）
• 补全：自动补全工具参数

Claude Code 技能

Claude Code 的预构建斜杠命令工作流，可协调多个工具，组成引导式运维手册：

技能	命令	描述
告警分流	/lm-triage	调查活动告警、评估噪声、关联告警集群、评估影响范围并采取行动
设备健康状况	/lm-health <device>	全面健康检查 — 指标、异常、健康评分、可用性、拓扑
门户概览	/lm-portal	面向交接班的全门户快照 — 告警、采集器、SDT、宕机设备
容量规划	/lm-capacity <device>	趋势分析、季节性检测、故障预测、合理调整资源规模
APM 调查	/lm-apm [service]	服务发现、操作级 RED 指标、告警关联
修复	/lm-remediate	诊断告警、查找/生成操作手册、启动 AAP 作业、验证修复结果

技能随仓库一同提供 — 克隆仓库并在 Claude Code 中调用 /lm-triage 即可开始使用。

运维功能

• 安全优先：默认只读，写操作需要明确选择启用
• 速率限制处理：使用指数退避和抖动自动重试
• 服务器错误恢复：对幂等请求（GET、PUT、DELETE）的 5xx 服务器错误自动重试；对于收到 5xx 的 POST 或 PATCH 请求，不会重新发送，因为服务器可能已经执行了该请求。超时和连接中断会报告，但不会重新发送
• 分页支持：使用基于偏移量的分页处理大型结果集
• 会话持久化：可选的文件支持会话变量，重启后仍会保留

多门户模式（可选）

通过单个服务入口跨多个客户门户工作，而不必为每个门户分别设置一个服务（和一个令牌）。设置 LM_MULTI_PORTAL=true 并将服务指向凭据库；完整工具集只加载一次，之后即可在运行时切换活动门户。通过四个工具进行管理：list_portals、use_portal、current_portal 和 reload_portals。凭据来自 age 加密凭据库（或用于测试的明文 JSON 文件），而非环境变量；每个门户都默认只读，除非明确标记为可写 — 因此，助手可以浏览任何门户，但不会意外更改门户。多门户模式仅支持 stdio（服务拒绝通过 HTTP 传输启动该模式），且其中无法使用 Terraform 工具。未修改的单门户行为保持不变（不设置 LM_MULTI_PORTAL，使用固定的 LM_PORTAL + 令牌）。参见 MULTIPORTAL.md。

安装

通过 PyPI 安装（推荐）

# Using uvx (no install needed)
uvx --from lm-mcp lm-mcp-server

# Using pip
pip install lm-mcp

从源码安装

git clone https://github.com/ryanmat/mcp-server-logicmonitor.git
cd mcp-server-logicmonitor
uv sync

Docker 部署

使用 HTTP 传输进行远程／共享部署：

cd deploy
cp .env.example .env
# Edit .env with your credentials, including LM_HTTP_AUTH_TOKEN (required)

# Run with docker-compose
docker compose up -d

# With TLS via Caddy
docker compose --profile tls up -d

服务器为容器编排提供健康检查端点：

• GET /health - 详细健康检查，包含所有组件状态（启用 LM API 连通性检查时，对于提供 LM_HTTP_AUTH_TOKEN 的调用方，或未设置令牌时，会增加该检查）
• GET /healthz - 存活探针（200 OK 或 503）
• GET /readyz - 就绪探针（仅执行本地检查；绝不调用 LM API）

发送到 /mcp 和 /api/v1/* 的 POST 请求必须使用 Content-Type: application/json；其他任何请求体类型都会得到 415 响应。除 /healthz 和 /readyz 外的所有路由（包括 /health）只响应服务器预期的 Host 名称（环回名称、非通配符 LM_HTTP_HOST 和 LM_HTTP_ALLOWED_HOSTS），其他名称会收到 400 响应；这两个探针接受任意 Host，以确保通过 Pod IP 进行的探测仍可正常工作。所有配置文件都要求设置 LM_HTTP_AUTH_TOKEN，compose 文件还会将 DOMAIN 传递为允许的主机，以供 Caddy tls 配置文件使用。

Kubernetes

deploy/k8s/deployment.yaml 是一个与供应商无关的 Deployment 和 Service，运行已发布的 ghcr.io 镜像。它适用于 AKS、EKS、GKE、OpenShift 或原生 Kubernetes，从你创建的 Kubernetes Secret 中读取凭据，并将存活和就绪探针连接到上述端点。在创建文件顶部所述的 Secret 后，使用 kubectl apply -f deploy/k8s/deployment.yaml 应用配置。

配置

环境变量

变量	必填	默认值	说明
LM_PORTAL	是	-	LogicMonitor 门户主机名（例如，company.logicmonitor.com）
LM_BEARER_TOKEN	是*	-	API Bearer 令牌（至少 10 个字符）
LM_ACCESS_ID	否	-	LMv1 API 访问 ID（用于数据摄取 API）
LM_ACCESS_KEY	否	-	LMv1 API 访问密钥（用于数据摄取 API）
LM_ENABLE_WRITE_OPERATIONS	否	false	启用写入操作（创建、更新、删除）
LM_API_VERSION	否	3	API 版本
LM_TIMEOUT	否	30	请求超时时间（秒，范围：5-300）
LM_MAX_RETRIES	否	3	对受速率限制的请求，以及幂等请求（GET、PUT、DELETE）发生服务器错误时的最大重试次数；返回 5xx 的 POST 或 PATCH 请求不会重新发送（范围：0-10）
LM_RETRY_AFTER_CAP_SECONDS	否	120	重试间隔的最长等待时间。服务器的 Retry-After 可以将退避时间延长至此上限，但不会缩短等待时间
LM_TRANSPORT	否	stdio	传输模式：stdio（本地）或 http（远程）
LM_MULTI_PORTAL	否	false	通过运行时使用 use_portal 选择，从一个服务为多个客户门户提供服务。仅适用于 Stdio。
LM_VAULT_FILE	否	-	age 加密门户保险库的路径（多门户）
LM_AGE_KEY	否	-	用于解密保险库的 age 身份文件路径（多门户）
LM_PORTALS_FILE	否	-	明文 JSON 门户映射（多门户，仅用于测试；两者同时设置时，加密保险库优先）
LM_HTTP_HOST	否	0.0.0.0	HTTP 服务绑定地址。使用 LM_TRANSPORT=http 时，若地址不是 127.0.0.1、::1 或 localhost，则必须设置 LM_HTTP_AUTH_TOKEN 或 LM_HTTP_ALLOW_UNAUTHENTICATED=true，否则服务将拒绝启动。
LM_HTTP_PORT	否	8080	HTTP 服务端口
LM_CORS_ORIGINS	否	-	以逗号分隔的 CORS 来源（默认：无）
LM_HTTP_AUTH_TOKEN	否	-	要求访问 /mcp 和 /api/v1/* 时提供此 Bearer 令牌（至少 16 个字符）。若 LM_HTTP_HOST 不是环回地址，则启动时必须设置此项；默认值 0.0.0.0 也包括在内，除非设置 LM_HTTP_ALLOW_UNAUTHENTICATED=true。健康检查端点和 / 保持开放以供探测。仅适用于 HTTP 传输。
LM_HTTP_ALLOWED_HOSTS	否	-	以逗号分隔的 Host 名称；除 /healthz 和 /readyz 外，服务器仅接受这些路由上的主机名，以及 127.0.0.1、::1、localhost 和非通配符的 LM_HTTP_HOST（例如反向代理转发的公共名称）。仅适用于 HTTP 传输。
LM_HTTP_ALLOW_UNAUTHENTICATED	否	false	当没有 LM_HTTP_AUTH_TOKEN 时，允许在非环回的 LM_HTTP_HOST 上启动，适用于通过其他方式保护监听器的情况（如身份验证代理或专用网络）。仅适用于 HTTP 传输。
LM_SESSION_ENABLED	否	true	启用会话上下文跟踪
LM_SESSION_HISTORY_SIZE	否	50	保留在历史记录中的工具调用数量
LM_LOG_LEVEL	否	warning	日志级别：debug、info、warning 或 error。记录写入 stderr；写入审计行（成功时为 info，失败时为 warning）会对凭据类键（如 password、token、api_key 和 extra_vars）下的参数值、LogicMonitor 凭据属性（如 ssh.pass 和 snmp.community），以及 property_name 为凭据属性之一时的 property_value 进行脱敏
LM_FIELD_VALIDATION	否	warn	字段验证：off、warn 或 error
LM_ENABLED_TOOLS	否	-	以逗号分隔的要启用的工具名称或 glob 模式（例如，get_*,triage）。不能与 LM_DISABLED_TOOLS 同时使用。
LM_DISABLED_TOOLS	否	-	以逗号分隔的要禁用的工具名称或 glob 模式（例如，delete_*）。不能与 LM_ENABLED_TOOLS 同时使用。
LM_MCP_CATEGORIES	否	-	以逗号分隔的要包含的类别名称：read、write、delete、export、import、session、workflow。与 LM_ENABLED_TOOLS/LM_DISABLED_TOOLS 取交集组合，只会缩小范围，不会扩大范围。适用于有工具数量上限的客户端（例如，Cursor 的 40 个工具上限）。
LM_HEALTH_CHECK_CONNECTIVITY	否	false	在 /health 中为已通过身份验证的调用方加入 LM API ping（绝不会加入 /readyz）
LM_SESSION_PERSIST_PATH	否	-	持久化会话变量的文件路径（重启后仍保留）
LM_ANALYSIS_MAX_CONCURRENCY	否	4	可同时运行的分析工作流数量（/api/v1/analyze 和警报 webhook）；后续提交会被接受并以 pending 状态等待。最小值为 1。仅适用于 HTTP 传输。
AWX_URL	否	-	Ansible Automation Platform 控制器 URL（例如，https://aap.example.com）
AWX_TOKEN	否	-	AAP 个人访问令牌
AWX_VERIFY_SSL	否	true	验证 AAP 连接的 SSL 证书
AWX_TIMEOUT	否	30	AAP API 调用的请求超时时间（秒）
AWX_MAX_RETRIES	否	3	对受速率限制的 AAP 请求，以及幂等请求发生服务器错误时的最大重试次数；返回 5xx 的作业启动请求不会重新发送。Retry-After 可将退避时间延长至 120 秒
WATSONX_API_KEY	否	-	watsonx.ai 的 IBM Cloud API 密钥（启用 Granite TTM + NL 摘要）
WATSONX_URL	否	https://us-south.ml.cloud.ibm.com	IBM watsonx.ai 端点 URL
WATSONX_PROJECT_ID	否	-	IBM watsonx.ai 项目 ID
WATSONX_TIMEOUT	否	60	watsonx.ai API 调用的请求超时时间（秒）
TF_WORKSPACE_DIR	否	-	Terraform 工作区的根目录（启用 Terraform 工具）
TF_TERRAFORM_BINARY	否	terraform	terraform 二进制文件的路径
TF_TIMEOUT	否	300	Terraform 命令超时时间（秒）
TF_AUTO_APPROVE_ENABLED	否	false	启用 terraform apply/destroy 操作
HF_TTM_MODEL	否	ibm-granite/granite-timeseries-ttm-r2	HuggingFace TTM 模型名称或路径
HF_LLM_MODEL	否	ibm-granite/granite-3.3-2b-instruct	HuggingFace LLM 模型名称或路径
HF_DEVICE	否	auto	推理使用的 Torch 设备（cpu、cuda、mps、auto）
HF_CACHE_DIR	否	-	HuggingFace 模型缓存目录
*LM_BEARER_TOKEN 或同时设置 LM_ACCESS_ID 和 LM_ACCESS_KEY 是必需的。

身份验证方式

Bearer Token（推荐）：

• 配置更简单，适用于大多数操作
• 设置 LM_BEARER_TOKEN

LMv1 HMAC（数据摄取必需）：

• ingest_logs 和 push_metrics 工具必需
• 同时设置 LM_ACCESS_ID 和 LM_ACCESS_KEY
• 可与 Bearer token 搭配使用

获取 API 凭据

Bearer Token：

1. 登录 LogicMonitor 门户
2. 前往 Settings → Users and Roles → API Tokens
3. 创建新的仅 API 用户，或为现有用户添加令牌
4. 复制 Bearer token

LMv1 凭据：

1. 前往 Settings → Users and Roles → Users
2. 选择用户 → API Tokens 标签页
3. 创建或查看 Access ID 和 Access Key

MCP 客户端配置

快速入门介绍了 Claude Code。所有基于 JSON 的客户端（Cursor、Claude Desktop、Cline、GitHub Copilot、Gemini CLI、OpenAI Codex）都使用同一配置块运行同一服务：

{
  "mcpServers": {
    "logicmonitor": {
      "command": "uvx",
      "args": ["--from", "lm-mcp", "lm-mcp-server"],
      "env": {
        "LM_PORTAL": "yourcompany.logicmonitor.com",
        "LM_BEARER_TOKEN": "your-bearer-token"
      }
    }
  }
}

根据需要，将 LM_ENABLE_WRITE_OPERATIONS、LM_ACCESS_ID/LM_ACCESS_KEY（数据摄取）或 watsonx/Terraform 变量添加到 env。各客户端的配置文件位置和具体步骤（Claude Code、Cursor、Claude Desktop、OpenAI Codex、Cline、GitHub Copilot、Gemini CLI）请参阅 documentation/client-setup.md。

Cursor 的 40 工具上限

Cursor 只会加载前 40 个 MCP 工具，因此其余约 240 个工具对 Agent 不可见。使用 LM_MCP_CATEGORIES，将精选工具子集控制在上限以内。仅 workflow 类别（triage、diagnose、health_check、portal_overview、capacity_plan，以及评分/关联工具和 update_logicmodule）就约有 23 个工具，足以满足 80% 的使用场景：

"env": {
  "LM_PORTAL": "yourcompany.logicmonitor.com",
  "LM_BEARER_TOKEN": "your-bearer-token",
  "LM_MCP_CATEGORIES": "workflow"
}

LM_MCP_CATEGORIES 与 LM_ENABLED_TOOLS 通过交集组合（只会缩小范围，不会扩大范围）；未设置时，服务会返回全部 306 个工具。在多门户模式下，4 个门户工具不受类别筛选影响（它们是该模式的控制平面），也不计入精选工具集。请参阅 documentation/client-setup.md，查看精简的 LM_ENABLED_TOOLS 示例。

可用工具

306 个工具覆盖 LogicMonitor 的全部功能，以及可选的 Ansible Automation Platform、Terraform 和 IBM watsonx.ai 集成。完整的逐工具参考（包含每个工具及其参数和读写分类）见 documentation/tools.md；该文档由工具注册表生成，因此始终保持同步。

无需离开客户端，即可在运行时发现工具：

• search_tools：按名称和描述搜索所有工具
• lm://guide/tool-categories 资源：按领域分组的全部 306 个工具

工具分为以下类别：告警、告警规则、设备、指标、APM 跟踪、仪表板、SDT、采集器、网站、升级、设备属性、报告、DataSources、LogicModules（配置/事件/属性/拓扑/日志）、成本优化、操作（链和规则）、数据摄取、网络与拓扑、批处理作业、运维与审计、用户与访问、服务、网络扫描、OID、会话、关联与分析、基线、ML/统计分析、Ansible Automation Platform、修复、复合工作流和错误预算。

MCP 资源

该服务提供 26 个 API 参考资源：

架构资源

URI	描述
lm://schema/alerts	告警对象的字段、类型和描述
lm://schema/devices	设备对象的字段和类型
lm://schema/sdts	SDT（计划停机时间）对象的字段
lm://schema/dashboards	仪表板对象的字段
lm://schema/collectors	Collector 对象的字段
lm://schema/escalations	升级链对象的字段
lm://schema/reports	报告对象的字段
lm://schema/websites	网站检查对象的字段
lm://schema/datasources	DataSource 定义字段
lm://schema/users	用户对象的字段
lm://schema/audit	审计日志条目的字段

枚举资源

URI	描述
lm://enums/severity	告警严重级别：critical（4）、error（3）、warning（2）、info（1）
lm://enums/device-status	设备状态值：normal（0）、dead（1）等
lm://enums/sdt-type	SDT 类型：DeviceSDT、DeviceGroupSDT 等
lm://enums/alert-cleared	告警清除状态：true、false
lm://enums/alert-acked	告警确认状态：true、false
lm://enums/collector-build	Collector 构建类型：EA、GD、MGD

筛选器资源

URI	描述
lm://filters/alerts	告警查询的筛选字段和运算符
lm://filters/devices	设备查询的筛选字段和运算符
lm://filters/sdts	SDT 查询的筛选字段和运算符
lm://syntax/operators	筛选运算符：:、~、>、<、!:、!~、>:、<:

指南资源

URI	描述
lm://guide/tool-categories	按领域类别整理的全部 306 个工具
lm://guide/examples	常用筛选模式和查询示例
lm://guide/mcp-orchestration	将 LogicMonitor 与其他 MCP 服务组合使用的模式
lm://guide/best-practices	基于场景的最佳实践，包含建议和反模式
lm://guide/example-responses	关键工具的输出示例，帮助理解响应格式

MCP 提示词

为常见任务预先构建的工作流模板：

提示词	描述	参数
incident_triage	分析活跃告警、识别模式并提出根本原因建议	severity、time_window_hours
capacity_review	检查资源利用率并识别容量问题	group_id、threshold_percent
health_check	生成包含关键指标的环境健康摘要	include_collectors
alert_summary	按严重级别或资源分组生成告警摘要	group_by、hours_back
sdt_planning	为维护时段规划计划停机时间	device_ids、group_id
cost_optimization	分析云成本并寻找节省机会	provider、threshold_percent
audit_review	检查近期变更、登录和安全事件	hours_back、username
alert_correlation	关联不同设备的告警，以查找共同的根本原因	severity、hours_back、device_id、group_id
collector_health	评估 Collector 负载均衡、版本和故障转移准备情况	group_id
troubleshoot_device	针对特定设备的引导式故障排查	device_id
top_talkers	找出产生最多告警、最嘈杂的设备和数据源	hours_back、limit、group_by
rca_workflow	结合告警、拓扑和变更历史进行引导式根本原因分析	device_id、alert_id、hours_back
capacity_forecast	预测容量趋势和阈值超限情况	device_id、group_id、datasource、hours_back、threshold
remediate_workflow	诊断 LogicMonitor 告警，并通过 Ansible Automation Platform 进行修复	alert_id、device_id
remediation	执行 LogicMonitor 修复源，并在执行前进行安全检查	host_id、remediation_source_id

示例用法

配置完成后，用自然语言向助手提问。以下是一些典型示例（服务支持的功能远不止这些，涵盖全部 306 个工具）：

• “列出 LogicMonitor 中前 5 台设备”（快速检查连接）
• “显示过去一小时内的所有严重警报”
• “确认警报 LMA12345，并备注‘正在调查磁盘问题’”
• “设备 123 应用了哪些数据源？再获取过去一小时的 CPU 指标”
• “创建一个名为‘API Health’的仪表板，并添加一个图表小组件”
• “为设备 123 创建一个 2 小时的维护窗口（SDT）”
• “对过去 4 小时内的所有严重警报进行分类”
• “对设备 123 运行健康检查，然后为交接班提供门户概览”
• “预测设备 123 的内存何时会达到 90%”
• “如果设备 789 宕机，影响范围会有多大？”
• “今天在设备 123 上运行了哪些诊断？脚本输出了什么？”

对于高级用户，服务可直接接受 LogicMonitor 筛选语法，例如“获取筛选条件为 'displayName~"prod",hostStatus:"normal"' 的设备”。字符串值（包括 hostStatus 的值）都必须加引号。

开发

运行测试

uv run pytest -v

代码检查

uv run ruff check src tests
uv run ruff format src tests

项目结构

src/lm_mcp/
├── __init__.py           # Package exports
├── analysis.py           # Scheduled analysis workflows and store
├── awx_config.py         # AAP connection configuration
├── config.py             # Environment-based configuration
├── exceptions.py         # Exception hierarchy
├── health.py             # Health check endpoints
├── logging.py            # Structured logging
├── server.py             # MCP server entry point
├── session.py            # Session context with optional persistence
├── registry.py           # Tool definitions and handlers (TOOLS + AWX_TOOLS)
├── validation.py         # Field validation with suggestions
├── auth/
│   ├── __init__.py       # Auth provider factory
│   ├── bearer.py         # Bearer token auth
│   └── lmv1.py           # LMv1 HMAC auth
├── client/
│   ├── __init__.py       # Client exports
│   ├── api.py            # Async HTTP client for LogicMonitor API
│   └── awx.py            # Async HTTP client for AAP controller API
├── completions/
│   └── registry.py       # Auto-complete definitions
├── prompts/
│   ├── registry.py       # Prompt definitions
│   └── templates.py      # Workflow template content
├── resources/
│   ├── registry.py       # Resource definitions
│   ├── schemas.py        # Schema content
│   ├── enums.py          # Enum content
│   ├── filters.py        # Filter content
│   ├── guides.py         # Tool categories, query examples, orchestration guide
│   ├── best_practices.py # Scenario-based best practices and anti-patterns
│   └── examples.py       # Example responses for key tools
├── transport/
│   ├── __init__.py       # Transport abstraction
│   └── http.py           # HTTP/SSE transport with analysis endpoints
└── tools/
    ├── __init__.py       # Tool utilities
    ├── alerts.py         # Alert management
    ├── alert_rules.py    # Alert rule CRUD
    ├── ansible.py        # Ansible Automation Platform tool handlers
    ├── baselines.py      # Metric baseline save/compare
    ├── collectors.py     # Collector tools
    ├── correlation.py    # Alert correlation, anomaly detection, metric correlation
    ├── cost.py           # Cost optimization
    ├── dashboards.py     # Dashboard CRUD
    ├── devices.py        # Device CRUD
    ├── escalations.py    # Escalation/recipient CRUD
    ├── event_correlation.py  # Change-alert correlation
    ├── forecasting.py    # Forecast, trend, seasonality, change points
    ├── imports.py        # LogicModule import
    ├── ingestion.py      # Log/metric ingestion
    ├── metrics.py        # Metrics and data
    ├── scoring.py        # Alert noise, availability, device health
    ├── sdts.py           # SDT management
    ├── session.py        # Session management tools
    ├── stats_helpers.py  # Shared statistical math utilities (incl. Holt-Winters, IQR, MAD)
    ├── topology_analysis.py  # Blast radius analysis
    ├── websites.py       # Website CRUD
    ├── workflows.py      # Composite workflow tools (triage, health_check, etc.)
    ├── metric_presets.py # Metric-type presets for auto-configuration
    └── ...               # Additional tool modules

examples/playbooks/
├── lm-remediate-disk-cleanup.yml
├── lm-remediate-service-restart.yml
├── lm-remediate-log-rotate.yml
└── lm-remediate-memory-cache-clear.yml

deploy/
├── Dockerfile            # Production Docker image
├── docker-compose.yml    # Full stack deployment
├── Caddyfile             # TLS proxy configuration
└── .env.example          # Environment template

故障排除

Claude Code 中出现“Failed to connect”

如果 claude mcp list 显示 ✗ Failed to connect，则服务缺少环境变量。添加服务时必须包含 -e 标志：

# Remove the broken config
claude mcp remove logicmonitor

# Re-add with environment variables
claude mcp add logicmonitor \
  -e LM_PORTAL=yourcompany.logicmonitor.com \
  -e LM_BEARER_TOKEN=<your-bearer-token> \
  -- uvx --from lm-mcp lm-mcp-server

**注意：**在 Shell 或 .env 文件中设置环境变量不起作用——Claude Code 会在独立环境中将 MCP 服务作为子进程启动。

“Write operations are disabled”

默认情况下，写入操作（确认警报、创建 SDT 等）处于禁用状态。请在环境中设置 LM_ENABLE_WRITE_OPERATIONS=true。

Claude Desktop 中出现“spawn uvx ENOENT”

Claude Desktop 找不到 uvx。请使用完整路径：

{
  "command": "/Users/yourname/.local/bin/uvx",
  "args": ["--from", "lm-mcp", "lm-mcp-server"]
}

使用 which uvx 查找 uvx 路径。

采集 API 错误

ingest_logs 和 push_metrics 工具需要 LMv1 身份验证。Bearer 令牌无法用于采集 API。请在配置中添加 LM_ACCESS_ID 和 LM_ACCESS_KEY。

速率限制错误

服务会自动采用指数退避策略重试受到速率限制的请求。如果持续触及限制，请降低请求频率或联系 LogicMonitor 支持团队。

身份验证错误

请确认 Bearer 令牌正确且具备相应权限。可在 LogicMonitor 的 Settings → Users and Roles → API Tokens 中管理 API 令牌。

许可证

MIT 许可证——详见 LICENSE 文件。