使用说明

项目简介

VictoriaMetrics MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，它扩展了 VictoriaMetrics 时序数据库的功能，使其能够通过 MCP 协议与 LLM 应用进行交互。该服务器主要提供工具 (Tools) 功能，允许 LLM 客户端调用 VictoriaMetrics 的数据查询和写入能力，从而为 LLM 应用提供实时的监控数据和指标数据。

主要功能点

数据查询工具 (vm_data_query, vm_data_range_query): 允许 LLM 客户端使用 MetricsQL 查询语言从 VictoriaMetrics 数据库中检索指标数据。支持即时查询和范围查询，可以根据时间范围和步长获取数据。
数据写入工具 (vm_data_write): 允许 LLM 客户端将新的指标数据写入 VictoriaMetrics 数据库。支持指定指标的标签 (metric)、值 (values) 和时间戳 (timestamps)。
基于 MCP 协议: 采用标准的 MCP 协议与客户端通信，易于集成到任何支持 MCP 协议的 LLM 应用中。
使用 Stdio 传输: 服务器和客户端通过标准输入输出 (stdio) 进行通信，简化部署和配置。

安装步骤

安装 Node.js 和 npm: 确保你的环境中已安装 Node.js 和 npm。
全局安装 '@yincongcyincong/victoriametrics-mcp-server': 打开终端，运行以下命令全局安装该 MCP 服务器。
```
npm install -g @yincongcyincong/victoriametrics-mcp-server
```
或者，你也可以选择在本地安装并在项目中使用 npx 运行。

服务器配置

MCP 服务器是为 MCP 客户端设计的，客户端需要配置服务器的启动命令才能连接。以下是客户端需要配置的 JSON 格式服务器信息，用于启动 VictoriaMetrics MCP Server。

{
    "mcpServers": {
        "vm-metrics": {  //  服务器名称，客户端用于标识和引用
            "command": "npx",  //  启动服务器的命令，这里使用 npx 运行 npm 包
            "args": [  //  命令参数
                "-y",  //  npx 参数，自动确认执行包
                "@yincongcyincong/victoriametrics-mcp-server"  //  要执行的 npm 包名称，即 VictoriaMetrics MCP Server
            ],
            "env": {  //  环境变量配置
                "VM_URL": "http://127.0.0.1:8428",  //  VictoriaMetrics 的基本 URL，例如：http://<VictoriaMetrics-IP>:<port>，用于查询和写入。如果 VM_URL 为空，则会尝试使用 VM_SELECT_URL 和 VM_INSERT_URL。请根据你的 VictoriaMetrics 部署地址进行修改。
                "VM_SELECT_URL": "",  //  可选：VictoriaMetrics 的查询 URL，如果 VM_URL 为空，则使用此 URL 进行查询。
                "VM_INSERT_URL": ""   //  可选：VictoriaMetrics 的写入 URL，如果 VM_URL 为空，则使用此 URL 进行写入。
            }
        }
    }
}

注意:

请将 'VM_URL' (或 'VM_SELECT_URL' 和 'VM_INSERT_URL') 替换为你的 VictoriaMetrics 服务器的实际地址。
'server name' 可以自定义，例如 "vm-metrics"，客户端将使用此名称来引用该服务器。
MCP 客户端会读取以上 JSON 配置，并根据 'command' 和 'args' 启动 VictoriaMetrics MCP Server，并通过 stdio 与之通信。

基本使用方法

启动 MCP 客户端: 配置好上述服务器信息后，启动你的 MCP 客户端应用。客户端会根据配置自动启动 VictoriaMetrics MCP Server。
列出工具: 在 MCP 客户端中，你可以发送 'ListToolsRequest' 请求到 VictoriaMetrics MCP Server，以获取可用的工具列表。服务器会返回包含 'vm_data_query', 'vm_data_range_query', 'vm_data_write' 这三个工具的响应。
调用工具: 使用 MCP 客户端发送 'CallToolRequest' 请求来调用具体的工具。
- 例如，调用 'vm_data_query' 工具: 你需要构造 'CallToolRequest'，指定 'tool_name' 为 '"vm_data_query"'，并在 'arguments' 中提供 MetricsQL 查询语句 'query'。服务器会执行查询，并将 VictoriaMetrics 返回的数据封装在 MCP 响应中返回给客户端。
- 例如，调用 'vm_data_write' 工具: 你需要构造 'CallToolRequest'，指定 'tool_name' 为 '"vm_data_write"'，并在 'arguments' 中提供要写入的指标数据，包括 'metric' (指标标签), 'values' (值数组), 'timestamps' (时间戳数组)。服务器会将数据写入 VictoriaMetrics，并返回操作结果。

示例 (MCP 客户端请求 - 仅供理解概念，实际请求格式请参考 MCP 协议文档):

ListToolsRequest:

{
  "jsonrpc": "2.0",
  "method": "ListTools",
  "params": {},
  "id": 1
}

CallToolRequest (vm_data_query):

{
  "jsonrpc": "2.0",
  "method": "CallTool",
  "params": {
    "name": "vm_data_query",
    "arguments": {
      "query": "up"
    }
  },
  "id": 2
}

CallToolRequest (vm_data_write):

{
  "jsonrpc": "2.0",
  "method": "CallTool",
  "params": {
    "name": "vm_data_write",
    "arguments": {
      "metric": {"job": "demo", "instance": "localhost"},
      "values": [1, 0],
      "timestamps": [1678886400000, 1678886460000]
    }
  },
  "id": 3
}

请参考 Model Context Protocol (MCP) 官方文档和你的 MCP 客户端的具体文档，了解如何发送 MCP 请求以及处理服务器响应。

关键词