Waldur MCP Server 使用说明

项目简介

Waldur MCP Server 是一个基于 Model Context Protocol (MCP) 构建的后端服务，旨在作为 Claude Desktop 等 LLM 客户端与 Waldur 云管理平台之间的桥梁。它允许 LLM 通过标准化的 MCP 协议访问 Waldur 平台的数据和功能，从而实现更智能的应用集成。

主要功能点

数据访问 (Resources): 提供 Waldur 数据库的 schema 信息，允许 LLM 理解数据结构。
工具调用 (Tools):
- 执行 SQL 查询 (只读)。
- 列出 Waldur 平台的客户、项目、资源、发票和产品。
- 创建用户邀请，邀请用户加入项目或组织。
Prompt 模板 (Prompts): 提供 schema 感知的 SQL 查询 Prompt 模板，辅助 LLM 生成更准确的 SQL 查询。

安装步骤

安装 Claude Desktop: 如果尚未安装，请从 Claude Desktop releases page 下载并安装适合您平台的 Claude Desktop 应用程序。
安装 Python: 确保您的系统已安装 Python 3.10 或更高版本。

安装 'waldur-mcp-server' 包: 打开终端或命令提示符，运行以下命令安装 Waldur MCP Server：

pip install waldur-mcp-server

或者使用 'uv' 包管理器：

uv pip install waldur-mcp-server

服务器配置

要让 Claude Desktop 连接到 Waldur MCP Server，您需要编辑 Claude Desktop 的配置文件 'claude_desktop_config.json'。该文件通常位于：

Windows: '\AppData\Roaming\Claude\claude_desktop_config.json'
MacOS: '~/Library/Application\ Support/Claude/claude_desktop_config.json'

在 'claude_desktop_config.json' 文件中，找到 '"mcpServers"' 部分（如果不存在则创建），并添加 'waldur-mcp-server' 的配置。以下是两种配置示例：

开发/未发布服务器配置 (Development/Unpublished Servers Configuration):

适用于开发和测试环境。您需要指定 Waldur MCP Server 代码所在的目录。

{
  "mcpServers": {
    "waldur-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/waldur_service_directory",  // 将 "/path/to/your/waldur_service_directory" 替换为 Waldur MCP Server 代码所在的实际目录
        "run",
        "waldur-mcp-server"
      ],
      "env": {
        "WALDUR_API_URL": "https://your-waldur-instance/api", // 将 "https://your-waldur-instance/api" 替换为您的 Waldur API 地址
        "WALDUR_TOKEN": "your-waldur-token" // 将 "your-waldur-token" 替换为您的 Waldur API Token
      }
    }
  }
}

已发布服务器配置 (Published Servers Configuration):

适用于已安装为 Python 包的服务器。

{
  "mcpServers": {
    "waldur-mcp-server": {
      "command": "uvx",
      "args": [
        "waldur-mcp-server"
      ],
      "env": {
        "WALDUR_API_URL": "https://your-waldur-instance/api", // 将 "https://your-waldur-instance/api" 替换为您的 Waldur API 地址
        "WALDUR_TOKEN": "your-waldur-token" // 将 "your-waldur-token" 替换为您的 Waldur API Token
      }
    }
  }
}

配置参数说明:

'"command"': 运行 MCP 服务器的命令。通常为 'uv'（或 'uvx'）或 'python'。
'"args"': 传递给 'command' 的参数列表。
- '--directory' (仅开发配置): 指定 Waldur MCP Server 代码所在的目录。
- 'run waldur-mcp-server' 或 'waldur-mcp-server': 指示运行 'waldur-mcp-server' 包。
'"env"': 环境变量配置。
- '"WALDUR_API_URL"': 您的 Waldur 平台 API 的 URL 地址。
- '"WALDUR_TOKEN"': 用于访问 Waldur API 的 Token。

重要: 请务必将示例配置中的占位符路径、API URL 和 Token 替换为您实际的值。

基本使用方法

启动 Claude Desktop: 完成配置后，启动 Claude Desktop 应用程序。
连接 MCP 服务器: Claude Desktop 应该会自动连接到配置的 Waldur MCP Server。
在 Claude 中使用: 您可以在 Claude 中指示其使用 Waldur MCP Server 提供的功能。例如，您可以询问 Claude 关于 Waldur 平台数据的问题，或者指示其执行特定的操作，如列出客户或创建用户邀请。

调试

如果需要调试 MCP 服务器，可以使用 MCP Inspector 工具。按照 MCP Inspector 的文档指引运行，可以帮助您监控和调试 MCP 服务器与客户端之间的通信。

npx @modelcontextprotocol/inspector uv --directory C:\\waldur_service run waldur-mcp-server

请根据您的实际配置调整上述命令。

关键词