Cfnlint MCP

cfn-lint MCP 服务器（概念验证）

通过作为MCP工具暴露的cfn-lint验证AWS CloudFormation模板。

安装

# Clone repository
git clone 
cd cfn-lint-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

Claude 桌面配置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "cfn-lint": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "--directory",
        "[YOUR DIRECTORY TO THE MPC SERVER]",
        "run",
        "-m",
        "cfnlintmcp.server"
      ],
      "env": {
        "GITHUB_TOKEN": "optional_token_here"
      }
    }
  }
}

独立运行

# Using uv (recommended)
uv --directory /Users/brianterry/Documents/repos/guard-mcp run -m cfnlintmcp.server

# Using python directly
python -m cfnlintmcp.server

测试

pytest -q

它是如何工作的

• 服务器通过标准输入输出（stdio）实现MCP协议，并由您的MCP主机（例如，Claude Desktop）启动。
• 启动时，它会进行一次性的GitHub检查以获取最新版本 cfn-lint 释放并缓存结果到内存中。
• 它使MCP工具能够验证CloudFormation模板并检查版本信息。一个专用的升级工具可以让主机（LLM）请求用户同意，然后进行更新 cfn-lint 自动地。
• 验证使用 cfnlint.api.lint 针对内存中的模板内容进行检查；结果以结构化的JSON格式返回，包括规则元数据和位置信息。

可用工具

• 验证CloudFormation模板

- 输入：{ "template_content": 字符串, "regions"?: 字符串数组, "ignore_checks"?: 字符串数组 } - 输出：{ "valid": 布尔值, "cfn_lint_version": 字符串, "matches": 匹配项数组 }

• “validate_with_guard”可以翻译为“使用守护机制进行验证”

- 输入：{ "模板内容": 字符串, "规则"?: 字符串 } - 输出：守卫结果字典（成功、匹配项、守卫版本等） - 注：使用 guardpycfn 安装时打包；否则返回有用的错误信息。安装方式：

    pip install guardpycfn

PyPI（Python Package Index）： “guardpycfn” 可以翻译为“守护pyc文件”或“保护pyc配置文件”，具体翻译取决于上下文，但通常指的是对某种与Python编译后的字节码文件（.pyc）相关的配置或文件进行保护或守护的操作。如果“pycfn”是一个特定软件、系统或配置的名称，那么可能需要更具体的翻译或解释。在没有具体上下文的情况下，上述翻译是一个较为通用的表述

• 获取服务器信息

- 输入：{} - 输出：{ "服务器版本", "cfn_lint版本", "MCP协议版本", "最新cfn_lint版本", "有可用升级", "上次版本检查时间" }

• 升级_cfn_lint（或：升级CFN Lint工具）

- 输入：{ "prefer_uv"?: boolean }（可选参数：prefer_uv，类型为布尔值） - 输出：{ "状态": "成功"|"无操作"|"失败", "之前版本", "之后版本", "使用的命令", "消息", "是否需要重启", "日志" }

示例：验证模板

请求（由MCP主机发送的JSON-RPC）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "validate_cloudformation_template",
    "arguments": {
      "template_content": "AWSTemplateFormatVersion: '2010-09-09'\nResources:\n  MyBucket:\n    Type: AWS::S3::Bucket\n",
      "regions": ["us-east-1"],
      "ignore_checks": []
    }
  }
}

响应（文本内容包含JSON）：

{
  "valid": true,
  "cfn_lint_version": "1.40.1",
  "matches": []
}

无效响应示例（已截断）：

{
  "valid": false,
  "cfn_lint_version": "1.40.1",
  "matches": [
    {
      "rule": {
        "id": "E3030",
        "shortdesc": "Check if properties have a valid value",
        "description": "Check if properties have a valid value in case of an enumator"
      },
      "message": "'invalid.type' is not one of [...]",
      "location": {
        "path": ["Resources", "MyInstance", "Properties", "InstanceType"],
        "start": { "line": 7, "column": 7 },
        "end": { "line": 7, "column": 19 }
      },
      "level": "error"
    }
  ]
}

示例：获取服务器信息

{
  "server_version": "0.1.0",
  "cfn_lint_version": "1.40.1",
  "mcp_protocol_version": "2024-11-05",
  "latest_cfn_lint_version": "1.40.1",
  "upgrade_available": false,
  "last_version_check": "2025-10-10T14:30:00Z"
}

示例：通过MCP升级cfn-lint

1. 主机（大型语言模型）提示用户：“cfn-lint 有新版本可用（1.41.0）。现在更新吗？”
2. 在获得同意后，主机调用工具：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "upgrade_cfn_lint",
    "arguments": { "prefer_uv": true }
  }
}

可能的结果：

{
  "status": "SUCCESS",
  "before_version": "1.40.1",
  "after_version": "1.41.0",
  "used_command": ["/opt/homebrew/bin/uv", "pip", "install", "-U", "cfn-lint"],
  "message": "cfn-lint upgraded",
  "restart_required": true,
  "logs": ["..."]
}

注：服务器不会自动重启；您需要重启或重新启动您的MCP主机以加载新版本。

与大型语言模型（以Claude Desktop为例）一起使用

一旦在Claude Desktop中完成配置（参见上述配置步骤），您就可以自然地与大型语言模型（LLM）对话。LLM将决定何时调用MCP工具。

内联验证模板

你：“在 us-east-1 区域验证这个 CloudFormation 模板”，然后粘贴你的模板。

大语言模型（LLM）将会调用 validate_cloudformation_template 使用您粘贴的内容，并返回结构化的查找结果（规则ID、消息以及行/列范围）。如果没有匹配项，则表示该模板对于给定的规则和区域是有效的。

检查服务器和cfn-lint版本

你：“服务器使用的是哪个版本的 cfn-lint？”

大语言模型（LLM）将会调用 get_server_info 并总结 cfn_lint_version， latest_cfn_lint_version以及是否可以进行升级。

提供并执行升级（用户可选择参与）

如果检测到更新的cfn-lint版本，大型语言模型（LLM）可以询问：“有新的cfn-lint版本可用（X.Y.Z）。您现在想要我进行升级吗？”

• 如果你说“是”：大型语言模型（LLM）会致电 upgrade_cfn_lint （可选地与 prefer_uv=true）。 该工具会在运行环境中升级cfn-lint，并返回升级前后的版本以及日志。
• 升级成功后，大型语言模型（LLM）将指示您（或您的主机）重启MCP服务器，以便加载新版本。

示例提示

• “为 us-west-2 区域验证此 CloudFormation 模板，并忽略 W2001 错误”
• “显示cfn-lint的版本以及是否有可用的升级”
• “升级 cfn-lint 然后重新验证我的模板”

环境变量

• GITHUB_TOKEN （可选）：提高GitHub API的版本检查限制。
• CFN_LINT_MCP_LOG_LEVEL （可选）：日志级别（默认： INFO）。