MetricFlow MCP 服务器实现

关键词

指标查询LLM 集成自助分析dbt 语义层数据接口

使用说明内容（Markdown格式）

  • 项目简介

    • 该仓库实现一个后端服务 MetricFlow Server，同时内置了对 Model Context Protocol (MCP) 的支持。通过 /mcp 路径提供 MCP 服务，使 LLM 客户端能够发现指标、获取维度值并执行查询等操作，从而在对话场景中获得可执行的数据能力与功能。服务还提供 REST API 端点用于指标浏览、查询执行以及清单刷新。

  • 主要功能点

    • MCP 接口：提供 list_metrics、get_dimension_values、query_metrics 三个工具，允许 AI 客户端以统一的工具集合访问指标信息、维度值以及执行查询。
    • 安全与鉴权：MCP 与 REST API 共用 API Key（MF_API_KEY），对 MCP 请求也进行鉴权保护。
    • 资源与工具管理：通过 POST /admin/refresh 加载或热重载 dbt 语义清单（semantic_manifest.json），实现对指标结构与查询能力的暴露。
    • 数据查询能力：后端通过 MetricFlow 引擎执行查询并返回结构化结果（包括 SQL 以及表格数据），支持与 PyArrow、数据分析工具对接。
    • 适配器、多库支持：内置对多种数据仓库适配器的初始化，支持 BigQuery、ClickHouse、Databricks、PostgreSQL、Redshift、Snowflake 等。
    • 易于集成：配合 Claude Desktop、Copilot 等 AI 助手进行无缝集成。

  • 安装步骤

    • 克隆仓库并安装依赖。
    • 按照 README 提供的 Quickstart 进行本地运行（安装 uv、配置环境变量 MF_API_KEY、MF_ADMIN_KEY、MF_DBT_PROFILE_NAME 等），或者使用 Docker 构建镜像并在容器中运行。
    • 初次启动后，通过 POST /admin/refresh 上传 semantic_manifest.json，以完成 Manifest 加载，MCP 服务随之启用。

  • 服务器配置（MCP 客户端配置信息） 该信息用于 MCP 客户端连接并使用 MCP 服务。以下为示例描述，请按实际部署环境替换地址与密钥等参数。 { "server_name": " metricflow ", "command": "uvicorn", "args": ["metricflow_server.main:app", "--host", "0.0.0.0", "--port", "8080"], "mcp_endpoint": "http://<你的服务器地址>:8080/mcp", "auth": { "type": "bearer", "token_env_var": "MF_API_KEY" } } 注释：server_name 为 MCP 服务标识；command/args 指定启动 MCP 服务的命令及其参数，确保服务器监听在 mcp 端点暴露的路径上；mcp_endpoint 指向 /mcp 的网络入口；auth 说明 Bearer 认证方式及 MF_API_KEY 的环境变量名，实际部署时请在部署环境中配置对应的 API Key。

  • 基本使用方法

    1. 启动服务器：根据环境选择本地启动或容器化部署，确保 MF_API_KEY、MF_ADMIN_KEY、MF_DBT_PROFILE_NAME 等配置正确。
    2. 加载清单：通过 POST /admin/refresh 上传 semantic_manifest.json，系统在成功后进入就绪状态。
    3. 使用 MCP 客户端：在 Claude Desktop 等工具中将 MCP 服务器地址配置为服务器的 /mcp 路径，使用 Bearer Token 认证，将工具调用映射到 list_metrics、get_dimension_values、query_metrics。
    4. 运行与调试：通过 MCP 客户端发出请求，后端将返回标准化的 JSON 结果，包括指标列表、维度值及查询结果及其 SQL。

服务器信息

访问项目