Consul MCP Server

Consul MCP Server

用于与 HashiCorp Consul 服务发现和服务网格交互的 Model Control Protocol（MCP）服务。此实现遵循 Anthropic 的 MCP 规范，可让 Claude 通过自然语言交互分析微服务架构、创建图表、识别问题并提供建议。

什么是 Model Control Protocol？

Model Control Protocol（MCP） 是由 Anthropic 开发的一项规范，可让 Claude 等 AI 模型与外部工具和 API 交互。此实现将 AI Agent 连接到你的 Consul 基础架构，让你能够使用自然语言管理和分析服务。

功能

• 列出并分析在 Consul 中注册的服务
• 识别并诊断未通过的健康检查
• 生成服务网格架构图
• 检测服务连接问题并提供建议
• 获取有关服务负载均衡和资源利用率的 AI 洞察

要求

• Node.js 18+
• npm 或 yarn
• 正在运行的 Consul 实例（本地或远程）
• 集成了 Claude 的 Claude Desktop 或 Cursor IDE

安装

# Clone the repository
git clone https://github.com/3loka/consul-mcp-server.git
cd consul-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

配置

在根目录中创建 .env 文件，并添加以下变量：

CONSUL_HTTP_ADDR=http://localhost:8500
CONSUL_HTTP_TOKEN=your-consul-token
PORT=3000
USE_HTTP=true

• CONSUL_HTTP_ADDR：Consul 服务的地址
• CONSUL_HTTP_TOKEN：Consul 服务的 ACL 令牌
• PORT：HTTP 服务的端口
• USE_HTTP：设置为 "true" 以使用 HTTP 模式；使用 stdio 模式时省略

安装

在 Cursor 中安装

要在 Cursor 中安装并使用此 MCP 服务：

1. 在 Cursor 中，打开设置（⌘+,）并切换到“MCP”选项卡。

2. 点击“+ Add new MCP server”。

3. 输入以下内容：

   • 名称：consul-assistant
   • 类型：command
   • 命令：npx -y consul-mcp-server

4. 点击“Add”，然后向下滚动到该服务，点击“Disabled”以启用服务。

5. 如有需要，重启 Cursor，确保 MCP 服务已正确加载。

在 Claude Desktop 中安装

要在 Claude Desktop 中安装并使用此 MCP 服务：

1. 在 Claude Desktop 中，打开设置（⌘+,）并切换到“Developer”选项卡。

2. 点击窗口底部的“Edit Config”。

3. 编辑文件（~/Library/Application Support/Claude/claude_desktop_config.json），添加以下代码，然后保存文件。

{
  "mcpServers": {
    "consul-assistant": {
      "command": "npx",
      "args": ["-y", "consul-mcp-server"]
    }
  }
}

如果服务不在本地主机上，或已启用 ACL，请改用以下配置

{
    "mcpServers": {
      "consul-assistant": {
        "command": "npx",
        "args": ["-y", "consul-mcp-server"],
        "env": {
          "CONSUL_HTTP_ADDR": "http://<host/ip>:8500",
          "CONSUL_HTTP_TOKEN": "<ACL Token>"
        }
      }
    }
  }

4. 重启 Claude Desktop，确保 MCP 服务已正确加载。

示例提示词

连接后，尝试在 Claude 中使用以下提示词：

• “显示在 Consul 中注册的所有服务”
• “哪些服务的健康检查未通过？”
• “为我的服务网格连接创建图表”
• “分析哪些服务存在连接问题”
• “我的微服务架构整体健康状况如何？”
• “显示连接错误率较高的服务”

可用的 MCP 操作

此服务实现了以下 MCP 操作：

操作	描述
consul/get_services	获取 Consul 中所有服务的列表
consul/get_health_checks	获取健康检查，可按需筛选未通过的检查
consul/get_service_connections	获取服务连接及其状态
consul/create_service_diagram	创建服务关系的 Mermaid 图
consul/analyze_service	分析特定服务以识别问题
consul/get_service_metrics	获取特定服务的详细指标

运行演示环境

出于测试目的，你可以设置一个本地演示环境，其中多个微服务已在 Consul 中注册：

# Run the setup script (requires Docker and Docker Compose)
chmod +x ./demo/setup-demo.sh
./demo/setup-demo.sh

这将启动：

• 一个 Consul 服务器
• 多个演示微服务
• 在 Consul 中注册这些服务
• 设置一些服务网格连接和运行状况检查

演示指南

1. 启动演示环境：

   ./scripts/setup-demo.sh
   

2. 启动 MCP 服务：

   npm start
   

3. 将 Claude Desktop 或 Cursor 连接到你的 MCP 服务

4. 尝试以下演示场景：

   a. 获取服务概览：

   Show me all the services registered in my Consul instance.
   

   b. 检查是否存在失败的运行状况检查：

   Are any services experiencing health issues? What might be causing them?
   

   c. 创建服务网格图：

   Create a diagram showing the connections between my services.
   

   d. 分析连接问题：

   Which services are having trouble connecting to each other?
   

   e. 获取建议：

   Based on my service mesh setup, what improvements would you recommend?
   

开发

项目结构

• src/index.ts：主入口点
• src/resources/：Consul API 交互代码
• src/tools/：辅助功能，例如图表生成
• src/server/：MCP 服务组件
• src/mcp/：MCP 操作定义和处理程序
• src/prompts/：AI 交互的模板管理
• src/tests/：测试套件

运行测试

npm test

构建

npm run build

贡献

欢迎贡献！请随时提交拉取请求。

许可证

MIT