outlit-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Outlit MCP Server

Outlit MCP 服务器

Query customer intelligence data through 6 MCP tools covering customer and user profiles, revenue metrics, activity timelines, and raw SQL analytics access.

通过6款MCP工具查询客户智能数据，涵盖客户与用户档案、收入指标、活动时间线以及原生SQL分析访问功能。

Quick Start

快速开始

What you need	Tool
Browse/filter customers	`outlit_list_customers`
Browse/filter users	`outlit_list_users`
Single customer deep dive	`outlit_get_customer`
Customer activity history	`outlit_get_timeline`
Custom analytics / aggregations	`outlit_query` (SQL)
Discover tables & columns	`outlit_schema`

Before writing SQL: Always call

outlit_schema

first to discover available tables and columns.

所需功能	工具
浏览/筛选客户	`outlit_list_customers`
浏览/筛选用户	`outlit_list_users`
单个客户深度分析	`outlit_get_customer`
客户活动历史	`outlit_get_timeline`
自定义分析/聚合	`outlit_query` （SQL）
查看表与列结构	`outlit_schema`

编写SQL前注意事项： 请先调用

outlit_schema

来查看可用的表和列。

Common Patterns

常用模式

Find at-risk customers:

json

{
  "tool": "outlit_list_customers",
  "billingStatus": "PAYING",
  "noActivityInLast": "30d",
  "orderBy": "mrr_cents",
  "orderDirection": "desc"
}

Revenue breakdown (SQL):

json

{
  "tool": "outlit_query",
  "sql": "SELECT billing_status, count(*) as customers, sum(mrr_cents)/100 as mrr_dollars FROM customer_dimensions GROUP BY 1 ORDER BY 3 DESC"
}

识别高流失风险客户：

json

{
  "tool": "outlit_list_customers",
  "billingStatus": "PAYING",
  "noActivityInLast": "30d",
  "orderBy": "mrr_cents",
  "orderDirection": "desc"
}

收入细分（SQL）：

json

{
  "tool": "outlit_query",
  "sql": "SELECT billing_status, count(*) as customers, sum(mrr_cents)/100 as mrr_dollars FROM customer_dimensions GROUP BY 1 ORDER BY 3 DESC"
}

MCP Setup

MCP 配置

Get an API Key

获取API密钥

Go to Settings > MCP Integration in the Outlit dashboard (app.outlit.ai).

前往Outlit控制台的设置 > MCP集成页面（app.outlit.ai）。

Auto-Detection Setup

自动检测配置

Detect the current environment and run the appropriate setup command:

Check for Claude Code — If running inside Claude Code (check if

claude

CLI is available), run:

bash

claude mcp add outlit https://mcp.outlit.ai/mcp -- --header "Authorization: Bearer API_KEY"

Check for Cursor — If

.cursor/mcp.json

exists in the project or home directory, add to that file:

json

{
  "mcpServers": {
    "outlit": {
      "url": "https://mcp.outlit.ai/mcp",
      "headers": { "Authorization": "Bearer API_KEY" }
    }
  }
}

Check for Claude Desktop — If

claude_desktop_config.json

exists at

~/Library/Application Support/Claude/

(macOS) or

%APPDATA%/Claude/

(Windows), add to that file:

json

{
  "mcpServers": {
    "outlit": {
      "url": "https://mcp.outlit.ai/mcp",
      "headers": { "Authorization": "Bearer API_KEY" }
    }
  }
}

Ask the user for their API key if not provided. Replace

API_KEY

with the actual key.

检测当前环境并运行对应的配置命令：

检查是否为Claude Code环境 — 如果在Claude Code中运行（检查是否有
```
claude
```
CLI可用），执行：
bash
```
claude mcp add outlit https://mcp.outlit.ai/mcp -- --header "Authorization: Bearer API_KEY"
```

检查是否为Cursor环境 — 如果项目或主目录下存在

.cursor/mcp.json

文件，将以下内容添加到该文件：

json

{
  "mcpServers": {
    "outlit": {
      "url": "https://mcp.outlit.ai/mcp",
      "headers": { "Authorization": "Bearer API_KEY" }
    }
  }
}

检查是否为Claude Desktop环境 — 如果在macOS的

~/Library/Application Support/Claude/

目录或Windows的

%APPDATA%/Claude/

目录下存在

claude_desktop_config.json

文件，将以下内容添加到该文件：

json

{
  "mcpServers": {
    "outlit": {
      "url": "https://mcp.outlit.ai/mcp",
      "headers": { "Authorization": "Bearer API_KEY" }
    }
  }
}

如果用户未提供API密钥，请向其索要。将

API_KEY

替换为实际密钥。

Verify Connection

验证连接

Call

outlit_schema

to confirm the connection is working.

调用

outlit_schema

来确认连接是否正常。

Tool Reference

工具参考

outlit_list_customers

Filter and paginate customers.

Key Params	Values
`billingStatus`	NONE, TRIALING, PAYING, CHURNED
`hasActivityInLast` / `noActivityInLast`	7d, 14d, 30d, 90d (mutually exclusive)
`mrrAbove` / `mrrBelow`	cents (10000 = $100)
`search`	name or domain
`orderBy`	last_activity_at, first_seen_at, name, mrr_cents
`limit`	1-1000 (default: 20)
`cursor`	pagination token

筛选并分页查询客户。

关键参数	可选值
`billingStatus`	NONE, TRIALING, PAYING, CHURNED
`hasActivityInLast` / `noActivityInLast`	7d, 14d, 30d, 90d（二者互斥）
`mrrAbove` / `mrrBelow`	以美分为单位（10000 = 100美元）
`search`	客户名称或域名
`orderBy`	last_activity_at, first_seen_at, name, mrr_cents
`limit`	1-1000（默认值：20）
`cursor`	分页令牌

outlit_list_users

Filter and paginate users.

Key Params	Values
`journeyStage`	DISCOVERED, SIGNED_UP, ACTIVATED, ENGAGED, INACTIVE
`customerId`	filter by customer
`hasActivityInLast` / `noActivityInLast`	Nd, Nh, or Nm (e.g., 7d, 24h) — mutually exclusive
`search`	email or name
`orderBy`	last_activity_at, first_seen_at, email
`limit`	1-1000 (default: 20)
`cursor`	pagination token

筛选并分页查询用户。

关键参数	可选值
`journeyStage`	DISCOVERED, SIGNED_UP, ACTIVATED, ENGAGED, INACTIVE
`customerId`	按客户ID筛选
`hasActivityInLast` / `noActivityInLast`	Nd, Nh, 或 Nm（例如：7d, 24h）—— 二者互斥
`search`	邮箱或姓名
`orderBy`	last_activity_at, first_seen_at, email
`limit`	1-1000（默认值：20）
`cursor`	分页令牌

outlit_get_customer

Single customer deep dive. Accepts customer ID, domain, or name.

Key Params	Values
`customer`	customer ID, domain, or name (required)
`include`	`users` , `revenue` , `recentTimeline` , `behaviorMetrics`
`timeframe`	7d, 14d, 30d, 90d (default: 30d)

Only request the

include

sections you need — omitting unused ones is faster.

单个客户深度分析。支持传入客户ID、域名或名称。

关键参数	可选值
`customer`	客户ID、域名或名称（必填）
`include`	`users` , `revenue` , `recentTimeline` , `behaviorMetrics`
`timeframe`	7d, 14d, 30d, 90d（默认值：30d）

仅请求你需要的

include

模块——省略未使用的模块可提升响应速度。

outlit_get_timeline

Activity timeline for a customer.

Key Params	Values
`customer`	customer ID or domain (required)
`channels`	SDK, EMAIL, SLACK, CALL, CRM, BILLING, SUPPORT, INTERNAL
`eventTypes`	filter by specific event types
`timeframe`	7d, 14d, 30d, 90d, all (default: 30d)
`startDate` / `endDate`	ISO 8601 (mutually exclusive with timeframe)
`limit`	1-1000 (default: 50)
`cursor`	pagination token

客户的活动时间线。

关键参数	可选值
`customer`	客户ID或域名（必填）
`channels`	SDK, EMAIL, SLACK, CALL, CRM, BILLING, SUPPORT, INTERNAL
`eventTypes`	按特定事件类型筛选
`timeframe`	7d, 14d, 30d, 90d, all（默认值：30d）
`startDate` / `endDate`	ISO 8601格式（与timeframe互斥）
`limit`	1-1000（默认值：50）
`cursor`	分页令牌

outlit_query

Raw SQL against ClickHouse analytics tables. SELECT only. See SQL Reference for ClickHouse syntax and security model.

Key Params	Values
`sql`	SQL SELECT query (required)
`limit`	1-10000 (default: 1000)

Available tables:

events

customer_dimensions

user_dimensions

mrr_snapshots

针对ClickHouse分析表的原生SQL查询。仅支持SELECT语句。查看SQL参考文档了解ClickHouse语法和安全模型。

关键参数	可选值
`sql`	SQL SELECT查询语句（必填）
`limit`	1-10000（默认值：1000）

可用表：

events

customer_dimensions

user_dimensions

mrr_snapshots

。

outlit_schema

Discover tables and columns. Call with no params for all tables, or

table: "events"

for a specific table. Always call this before writing SQL.

查看表与列结构。不带参数调用可查看所有表，或传入

table: "events"

查看特定表。编写SQL前请务必先调用该工具。

Data Model

数据模型

Billing status: NONE → TRIALING → PAYING → CHURNED

Journey stages: DISCOVERED → SIGNED_UP → ACTIVATED → ENGAGED → INACTIVE

Data formats:

Monetary values in cents (divide by 100 for dollars)
Timestamps in ISO 8601
IDs with string prefixes (
```
cust_
```
,
```
contact_
```
,
```
evt_
```
)

Pagination: All list endpoints use cursor-based pagination. Check

pagination.hasMore

before requesting more pages. Pass

pagination.nextCursor

cursor

for the next page.

计费状态： NONE → TRIALING → PAYING → CHURNED

用户旅程阶段： DISCOVERED → SIGNED_UP → ACTIVATED → ENGAGED → INACTIVE

数据格式：

货币值以美分为单位（除以100转换为美元）
时间戳为ISO 8601格式
ID带有字符串前缀（
```
cust_
```
,
```
contact_
```
,
```
evt_
```
）

分页： 所有列表接口均使用基于游标（cursor）的分页。在请求更多数据前，请检查

pagination.hasMore

字段。将

pagination.nextCursor

作为

cursor

参数传入以获取下一页数据。

Best Practices

最佳实践

Call
outlit_schema
before writing SQL — discover columns, don't guess
Use customer tools for single lookups — don't use SQL for individual customer queries
Filter at the source — use tool params and WHERE clauses, not post-fetch filtering
Only request needed includes — omit unused
```
include
```
options for faster responses

Always add time filters to event SQL —

WHERE occurred_at >= now() - INTERVAL N DAY

Convert cents to dollars — divide monetary values by 100 for display
Use LIMIT in SQL — cap result sets to avoid large data transfers

编写SQL前先调用
outlit_schema
— 查看可用列，不要凭猜测编写
使用客户工具进行单个客户查询 — 不要使用SQL查询单个客户数据
在数据源端筛选 — 使用工具参数和WHERE子句进行筛选，而非获取数据后再筛选
仅请求所需的include模块 — 省略未使用的
```
include
```
选项以提升响应速度

事件SQL查询务必添加时间筛选 —

WHERE occurred_at >= now() - INTERVAL N DAY

将美分转换为美元 — 货币值除以100后再展示
SQL查询中使用LIMIT — 限制结果集大小以避免大量数据传输

Known Limitations

已知限制

SQL is read-only — no INSERT, UPDATE, DELETE
Organization isolation — cannot query other organizations' data
Timeline requires a customer — cannot query timeline across all customers
MRR filtering is post-fetch — may be slower on large datasets in list_customers
Event queries need time filters — queries without date ranges scan all data
ClickHouse syntax — uses different functions than MySQL/PostgreSQL (see SQL Reference)

SQL仅支持只读操作 — 不支持INSERT、UPDATE、DELETE
组织数据隔离 — 无法查询其他组织的数据
时间线查询必须指定客户 — 无法查询所有客户的汇总时间线
MRR筛选为后置处理 — 在
```
list_customers
```
中针对大型数据集进行MRR筛选可能较慢
事件查询需要时间筛选 — 未指定日期范围的查询会扫描所有数据
使用ClickHouse语法 — 与MySQL/PostgreSQL的函数不同（查看SQL参考文档）

Tool Gotchas

工具注意事项

Tool	Gotcha
`outlit_list_customers`	`hasActivityInLast` and `noActivityInLast` are mutually exclusive
`outlit_list_customers`	`search` checks name and domain only
`outlit_get_customer`	`behaviorMetrics` depends on timeframe — extend it if empty
`outlit_get_timeline`	`timeframe` and `startDate` / `endDate` are mutually exclusive
`outlit_query`	Use ClickHouse date syntax: `now() - INTERVAL 30 DAY` , not `DATE_SUB()`
`outlit_query`	`properties` column is JSON — use `JSONExtractString(properties, 'key')`

工具	注意事项
`outlit_list_customers`	`hasActivityInLast` 和 `noActivityInLast` 二者互斥
`outlit_list_customers`	`search` 仅匹配名称和域名
`outlit_get_customer`	`behaviorMetrics` 依赖于时间范围——若结果为空可扩大时间范围
`outlit_get_timeline`	`timeframe` 与 `startDate` / `endDate` 二者互斥
`outlit_query`	使用ClickHouse日期语法： `now() - INTERVAL 30 DAY` ，而非 `DATE_SUB()`
`outlit_query`	`properties` 列是JSON格式——使用 `JSONExtractString(properties, 'key')` 提取字段

References

参考文档

Reference	When to Read
SQL Reference	ClickHouse syntax, security model, query patterns
Workflows	Multi-step analysis: churn risk, revenue dashboards, account health

参考文档	阅读场景
SQL参考文档	ClickHouse语法、安全模型、查询模式
工作流文档	多步骤分析：流失风险、收入仪表盘、客户健康度