AI导哈

Datadog MCP 服务器

Datadog MCP 服务器是一个连接AI代理（如Cursor、Claude等）与Datadog的模型上下文协议服务器，支持日志搜索、指标查询、仪表盘管理、APM跟踪分析以及监控管理等功能。

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

使用说明

Datadog MCP服务器

A. 模型上下文协议 将AI代理（Cursor、Claude等）连接到Datadog的服务器。搜索日志、查询指标、管理仪表板、分析APM跟踪和管理监视器/停机时间——所有这些都可以通过您的AI助手，使用应用程序密钥的真实权限完成。

内置于 FastMCP 和Pydantic。没有删除，没有破坏性的仪表板/监视器删除，每个工具响应都是经过验证的Pydantic模型，具有一致的 success/error 形状。

建筑

  • server.py 是一个薄的合成层：它连接每个域的 register_<domain>_tools(mcp) 变成一个 FastMCP 实例并定义资源/提示。它不包含工具实现。
  • tools/*.py -每个Datadog域一个模块（日志、聚合、指标、apm、仪表板、监视器、停机时间）。每个模块都有自己的Pydantic模型 _function(...) 实现（显式注入身份验证，易于单元测试）及其 register_<domain>_tools(mcp) 功能与 @mcp.tool 装饰器+文档字符串。
  • auth.py -the DatadogAuth/get_auth_instance() 单身。与之前相同的环境变量(DD_API_KEY, DD_APP_KEY, DD_SITE)；本次改造中没有更改身份验证行为。
  • utils/response.py -共享Pydantic响应基础架构：入站 DatadogModel （宽容， extra="ignore")与出境 ToolResponse/PaginatedListResponse （严格， extra="forbid")基于大小的截断和Datadog错误分类（403→缺失范围，429→ 速率限制）。
  • utils/annotations.py -分享，诚实 ToolAnnotations 预设（见下表）。

看 建筑.md 对于完整的请求流和 文档/范围验证.md 对于每种工具背后的范围研究。

工具

所有工具名称、响应字段名称和环境变量在本次改进中都是稳定的，以下内容均未被重命名。总共30个工具。

🔍 日志

  • search_logs -搜索和查看日志条目（分页）
  • get_log_details -按ID列出的单个日志的完整详细信息
  • count_logs -快速计数与查询匹配的日志（无内容传输）
  • count_唯一值 -统计字段的唯一值（例如不同的用户）
  • aggregate_logs_by_field -使用统计数据对日志进行分组/聚合；可选的 interval 时间序列细分

📊 指标

  • query_metrics -使用聚合查询时间序列指标
  • list_available_metrics -发现与前缀匹配的度量名称
  • list_active_metrics -列出最近报告数据的指标
  • 描述度量 -元数据（单位、类型、描述）+一个指标的已知标签，在一次调用中
  • send_custom_metric -提交自定义指标（仪表、计数、费率）

📈 仪表盘

  • list_all_dashboards -浏览所有仪表板
  • get_dashboard_details -完整的仪表板配置和小部件（大型小部件列表用 warning，请参阅 finalize_list_response)
  • create_new_dashboard -使用小部件/布局创建仪表板（常见的小部件类型经过飞行前验证-请参阅 datadog://widget-templates)
  • update_existing_dashboard -修改现有仪表板（覆盖给定字段；无撤消工具）

根据设计，仪表板不存在删除工具。

🔬 APM/痕迹

  • search_apm_tracies -按服务、操作、标签进行搜索
  • get_full_trace -通过专用的每个跟踪端点，按跟踪ID进行完整跟踪（所有跨度）
  • list_apm_服务 -发现仪表化服务
  • aggregate_span -按方面分组的延迟/错误统计信息，无需提取原始跨度

🚨 监视器

  • list_all_监视器 -列出带有过滤器的监视器（状态、名称、标签）
  • 搜索监视器 -全文/分面显示器搜索
  • get_monitor_details -完整监视器配置
  • validate_monitor -在创建监视器查询/类型之前对其进行验证
  • create_alert_monitor -创建度量、日志、APM或复合监视器
  • update_alert_monitor -修改现有监视器的配置
  • 静音监视器 / unselence_monitor -将单个显示器静音/取消静音（一次性；请参阅计划/范围静音的停机时间）

根据设计，监视器不存在删除工具。

🌙 停机时间

  • list_downtimes -列出计划/活动停机时间
  • get_downtime -一次停机的完整细节
  • schedule_downtime -在一个时间窗口内将监视器范围（或一个监视器）静音
  • update_downtime -修改现有停机时间的计划/范围

不 cancel_downtime 工具：这是一个真实的、不可逆转的 DELETE 在团队明确签字之前，故意将其排除在外（见 utils/annotations.py).

资源

  • datadog://status -快速健康快照（提醒监视器计数/名称）；只进行一个Datadog API调用
  • datadog://widget-templates -即用型小部件JSON create_new_dashboard/update_existing_dashboard （时间序列、查询值、顶部列表、热图）

鼓励

  • 调查错误（服务、环境、回顾） -跨日志/APM/监视器的引导性错误调查
  • 性能分析（服务？，回顾） -引导性延迟/性能调查
  • 试验警报监视器（环境？） -对当前处于警报状态的监视器进行优先分类
  • create_monitoring（目标） -引导式监视器+仪表板创建

工具安全注释

每个工具都宣称诚实 ToolAnnotations 通过中的四个预设之一进行提示 utils/annotations.py:

预设 只读 破坏性 幂等 由使用
READ_ONLY ✅ ❌ ✅ 所有搜索/列表/获取/计数/聚合/验证工具
WRITE_ADDITIVE ❌ ❌ ❌ create_new_dashboard, create_alert_monitor, schedule_downtime, send_custom_metric
WRITE_OVERWRITE ❌ ✅ ✅ update_existing_dashboard, update_alert_monitor, update_downtime （即使没有删除任何内容，也不存在撤消工具）
STATE_TOGGLE ❌ ❌ ✅ silence_monitor / unsilence_monitor （可逆，存在匹配的反向工具）

安装

先决条件

  • Python 3.10+
  • 紫外线 （推荐）
  • 数据狗API密钥+应用程序密钥。此服务器使用的应用程序密钥只需要（请参阅 文档/范围验证.md 完整的理由）：
    • 阅读： logs_read, metrics_read, dashboards_read, monitors_read, apm_read
    • 写： metrics_write, dashboards_write, monitors_write, monitors_downtime_write

1.安装依赖项

cd /path/to/datadog-mcp
uv sync --frozen

uv sync --frozen 安装固定的内容 uv.lock -CI测试的版本相同。只有下降 --frozen （然后跑 uv lock --upgrade 第一）故意破坏依赖关系时。

2.配置游标 mcp.json

凭据属于Cursor的 mcp.json不在这个项目中。 这 .env.example repo根目录下的文件仅用于本地开发（例如运行 scripts/verify_scopes.py 直接）。

{
  "mcpServers": {
    "datadog": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/datadog-mcp",
        "run", "fastmcp", "run", "src/datadog_mcp/server.py"
      ],
      "env": {
        "DD_API_KEY": "${DD_API_KEY}",
        "DD_APP_KEY": "${DD_APP_KEY}",
        "DD_SITE": "datadoghq.com"
      }
    }
  }
}

集 DD_API_KEY/DD_APP_KEY 在您的shell配置文件中，并引用它们 ${...} 如上所述，或直接将原始值内联到 mcp.json （不太安全，更简单）。

数据狗区域 (DD_SITE): datadoghq.com （US1，默认）， us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com.

3.重新启动游标

重新启动Cursor IDE（或重新加载MCP服务器）以获取新服务器。

固定版本以进行回滚

光标的 mcp.json 可以指出 --directory 在特定的git工作树/标签/提交中。如果此服务器的更改导致团队崩溃，请固定 datadog-mcp 签出到最后一个已知的良好标记/提交并重新运行 uv sync --frozen 没有-回滚不需要更改代码。

发展

在本地运行

uv run fastmcp run --reload src/datadog_mcp/server.py   # dev server with auto-reload
uv run datadog-mcp                                       # or: run the installed script directly

测试

uv run pytest                # unit + MCP handshake + tool-schema snapshot tests
uv run pytest -m live         # opt-in: real Datadog API calls, requires DD_API_KEY/DD_APP_KEY
  • 握手测试 (tests/test_handshake.py)：通过以下方式在内存中启动服务器 fastmcp.Client，断言每个基线工具/资源/提示名称仍然存在，并端到端地往返模拟工具调用。这是防止导入错误导致整个团队服务器崩溃的安全网。
  • 架构快照测试 (tests/test_tool_schemas.py)：每个工具的输入/输出JSON模式都被捕获为黄金文件；任何形状变化都会显示在PR差异中，而不是悄无声息地到达客户端。通过使用它定义的更新标志运行一次测试，然后查看差异，重新生成有意更改的快照。
  • 现场测试 (pytest -m live)：默认情况下跳过（包括在CI中）在真实凭据后面门控的少数只读烟雾调用。

过梁和类型检查

uv run ruff check .
uv run ruff format .
uv run pyright src
uv run mypy src        # stricter, allowed to flag datadog-api-client's untyped calls (see inline `type: ignore[no-untyped-call]`)

CI(.github/workflows/ci.yml)跑拉夫， ruff format --check对锁定的依赖集的每个推送/PR进行pyright和pytest(uv sync --frozen). pre-commit 在提交之前，在本地运行相同的ruff/pyright检查。

添加一个新工具

  1. 添加Pydantic请求/响应模型和 _function(...) 实施相关 tools/<domain>.py （或新的域模块）。
  2. 注册 @mcp.tool(annotations=...)-该模块内的装饰包装 register_<domain>_tools(mcp)，文档字符串遵循中的约定 .cursor/rules/documentation-standards.mdc.
  3. 根据以下内容验证所需的Datadog范围 docs/SCOPE_VERIFICATION.md / scripts/verify_scopes.py 之前 编写工具-此应用程序密钥是此服务器独有的，并且具有固定的窄范围集。
  4. 在下添加单元测试 tests/tools/，然后运行完整套件-如果出现倒退，握手和模式快照测试将大声失败。

使用示例

Search Datadog logs for errors in the api service in the last hour
→ search_logs(query="status:error service:api", from_time="now-1h", to_time="now")

Show me CPU usage for all hosts over the last 4 hours
→ query_metrics(query="avg:system.cpu.user{*}", from_time="now-4h", to_time="now")

Create a dashboard called "API Performance" with a timeseries widget for request latency
→ create_new_dashboard(...) using a template from datadog://widget-templates

Mute all monitors in staging this weekend
→ schedule_downtime(scope="env:staging", ...)

What's currently alerting?
→ the triage_alerting_monitors prompt

故障排除

服务器未出现在游标中

  • 确认 --directory 路径在 mcp.json 是绝对和正确的。
  • 确认 DD_API_KEY/DD_APP_KEY 解析为实际值（如果使用，请检查您的shell配置文件 ${...} 插值）。
  • 完全重新启动Cursor并检查其MCP日志。

身份验证/403错误

  • 工具响应将403分类为可能缺失的范围-对照进行检查 docs/SCOPE_VERIFICATION.md.
  • 验证 DD_SITE 匹配您的Datadog地区；不匹配的站点的行为类似于身份验证失败。

拉取更改后的导入错误

uv sync --frozen

API文档

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

相关 MCP