Motley MCP Server

什么是 Motley MCP Server？

Motley MCP Server 是 Motley Cloud 的托管端点（https://app.motley.ai/api/v1/mcp），让 AI 智能体通过受治理的语义层查询你的数据、维护其中的模型和记忆，并生成报告，全部在对话中完成。

Motley 开发了面向 AI 智能体的开源语义层 SLayer，以及托管它的平台 Motley Cloud。Motley 不让智能体直接对数据仓库写原始 SQL，而是为它提供统一的度量、维度和关联定义，以及已保存的业务上下文（例如「财年从二月开始」「排除测试账户」），从而让同一个问题每次都得到同样的答案。Motley 以只读方式连接 Postgres、Snowflake、BigQuery、ClickHouse、Databricks、DuckDB 和 MySQL 等数据库。该 MCP 服务器面向希望让 Claude、ChatGPT、Copilot 或 Cursor 正确回答业务问题的数据团队和产品开发者。

如何使用 Motley MCP Server？

用工作邮箱在 app.motley.ai 注册（或请组织管理员邀请你），并连接一个数据源；欢迎页面提供了演示数据集。然后通过 URL 添加 MCP 服务器。浏览器会打开一个窗口，让你登录 Motley 账户并授权连接。

Claude Code

claude mcp add --transport http motley https://app.motley.ai/api/v1/mcp

在 Claude Code 中运行 /mcp，并在浏览器中完成 Motley 登录。Motley 文档也给出了等效的项目级 .mcp.json 配置：

{
  "mcpServers": {
    "motley": {
      "type": "http",
      "url": "https://app.motley.ai/api/v1/mcp"
    }
  }
}

Claude Desktop 与 claude.ai

打开 Settings，进入 Connectors，选择「Add custom connector」，命名为 Motley 并粘贴 https://app.motley.ai/api/v1/mcp。然后点击 Connect，在浏览器中登录 Motley。

Cursor

{
  "mcpServers": {
    "motley": {
      "url": "https://app.motley.ai/api/v1/mcp"
    }
  }
}

VS Code

{
  "servers": {
    "motley": {
      "type": "http",
      "url": "https://app.motley.ai/api/v1/mcp"
    }
  }
}

开始提问前，请确认服务器显示为已连接。

Motley MCP Server 的主要功能

• 一次调用即可对模型、列、度量和已保存的记忆进行语义搜索（search），让智能体在查询前看到正确的上下文。
• 使用 run_query 运行临时查询，返回原始行数据，不保存任何内容。
• 在对话中编辑模型：添加或修改列、度量和关联（create_measure、patch_column、create_join 等工具）；修改会作用于该数据源之后的所有查询。
• 通过 save_memory 保存记忆，避免以后的会话重新摸索数据中的同样问题。
• 文档与报告：创建文档并添加文本、表格、图表或查询区块。
• 每位组织成员通过 OAuth 登录，由基于角色的权限决定智能体能否编辑语义层，还是只能读取和查询。
• 每次工具调用都会记录在 Motley 的 Usage 视图中，管理员可通过工具查看会话并审阅智能体反馈。

Motley MCP Server 的使用场景

• 业务问题：「按门店看，平均客单价与去年相比有什么变化？」
• 探索语义层：「列出所有可用的模型，并说明每个模型涵盖什么。」
• 定义指标：「我们把月经常性收入定义为 status 为 'active' 的订阅金额之和。把它作为度量添加到 subscriptions 模型。」
• 修正定义：「revenue 度量应该用 sum，而不是 count。」
• 记录上下文：「orders.order_total 列的单位是美分而不是美元。添加一条记忆，让以后的查询在求和前先除以 100。」
• 报告：把查询结果变成包含表格和图表、可分享的文档。

Motley MCP Server 常见问题排查

• 智能体能查询但不能编辑模型：权限取决于你在 Motley 中的角色。请管理员为你分配允许编辑语义层的角色。
• 已添加服务器但未连接：完成浏览器中的登录授权，然后检查客户端是否显示服务器已连接。
• 查询结果不符合预期：让智能体解释查询为什么返回这样的结果，再用一条记忆记录下来，供下一次会话使用。
• 还没有可查询的数据：先在 Motley 应用中加载演示数据集或添加数据源。