内容
# AppSheet MCP 服务器
[](https://www.npmjs.com/package/appsheet-mcp-server)
[](https://opensource.org/licenses/MIT)
**谷歌 AppSheet 开源 MCP 服务器** — 使 AI 助手（Claude、Gemini、Cursor 等）能够通过模型上下文协议与您的 AppSheet 应用交互。
## 功能
- 🔍 **CRUD 操作** — 在任意 AppSheet 表中查找、添加、更新、删除行
- 📋 **架构发现** — 列出应用、表和列结构
- ⚡ **自定义操作** — 触发 AppSheet 操作和自动化机器人
- 🏢 **多应用支持** — 使用单个服务器配置多个应用
- 🔒 **安全** — API 密钥保留本地，不会暴露给 AI 模型
- 🚀 **零配置** — 只需 2 个环境变量即可使用
## 先决条件
- **Node.js 18+**
- **AppSheet 核心计划或更高** （API 访问需要付费计划）
- **AppSheet API 密钥** — 在 AppSheet 编辑器 → 设置 → 集成中生成
## 快速入门
### 1. 获取您的 API 密钥
1. 在编辑器中打开您的 AppSheet 应用
2. 进入 **设置 → 集成 → IN：来自云服务**
3. 启用 API 并复制 **应用程序访问密钥**
4. 从 URL 中记录您的 **应用 ID**：`https://www.appsheet.com/template/AppDef?appName=您的应用 ID`
### 2. 配置
#### 选项 A：环境变量（单个应用）
```bash
export APPSHEET_APP_ID="您的应用 ID"
export APPSHEET_API_KEY="V2-您的 API 密钥"
export APPSHEET_REGION="global" # 或 "eu" 或 "apac"
export APPSHEET_TABLES="客户,订单,产品" # 可选
```
#### 选项 B：配置文件（多个应用）
创建 `~/.appsheet-mcp.json`：
```json
{
"apps": {
"crm": {
"appId": "abc-123-def-456",
"apiKey": "V2-xxxxx-xxxxx",
"region": "global",
"tables": ["客户", "联系人", "交易"]
},
"inventory": {
"appId": "ghi-789-jkl-012",
"apiKey": "V2-yyyyy-yyyyy",
"region": "eu",
"tables": ["产品", "仓库", "订单"]
}
}
}
```
### 3. 连接到您的 AI 助手
#### Claude 桌面版
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"appsheet": {
"command": "npx",
"args": ["-y", "appsheet-mcp-server"],
"env": {
"APPSHEET_APP_ID": "您的应用 ID",
"APPSHEET_API_KEY": "V2-您的 API 密钥",
"APPSHEET_REGION": "global"
}
}
}
}
```
#### Cursor
在项目中添加到 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"appsheet": {
"command": "npx",
"args": ["-y", "appsheet-mcp-server"],
"env": {
"APPSHEET_APP_ID": "您的应用 ID",
"APPSHEET_API_KEY": "V2-您的 API 密钥"
}
}
}
}
```
#### VS Code
添加到 VS Code 设置或 `.vscode/mcp.json`：
```json
{
"mcpServers": {
"appsheet": {
"command": "npx",
"args": ["-y", "appsheet-mcp-server"],
"env": {
"APPSHEET_APP_ID": "您的应用 ID",
"APPSHEET_API_KEY": "V2-您的 API 密钥"
}
}
}
}
```
## 工具
### 数据操作（CRUD）
| 工具 | 描述 |
|------|-------------|
| `appsheet_find_rows` | 查询/搜索行，可选筛选表达式 |
| `appsheet_add_rows` | 向表中添加一行或多行 |
| `appsheet_update_rows` | 按关键列更新现有行 |
| `appsheet_delete_rows` | 按关键列值删除行 |
### 架构发现
| 工具 | 描述 |
|------|-------------|
| `appsheet_list_apps` | 列出所有配置的应用 |
| `appsheet_list_tables` | 列出应用中的表 |
| `appsheet_describe_table` | 从样本数据中发现列名和类型 |
### 自动化
| 工具 | 描述 |
|------|-------------|
| `appsheet_run_action` | 执行自定义 AppSheet 操作 |
| `appsheet_run_workflow` | 触发 AppSheet 自动化/机器人 |
### 实用工具
| 工具 | 描述 |
|------|-------------|
| `appsheet_get_app_info` | 获取应用配置摘要（无需 API 密钥） |
## 使用示例
连接后，询问您的 AI 助手：
> "显示客户表中的所有客户"
> "添加一个新订单，客户为 'Acme Corp'，产品为 'Widget'，数量为 50"
> "将订单 #123 的状态更新为 '已发货'"
> "我的 CRM 应用中有哪些表？"
> "描述产品表的结构"
> "在订单 #456 上运行 '发送发票' 操作"
## 筛选表达式
`appsheet_find_rows` 工具支持 AppSheet 筛选表达式：
```
# 查找活跃客户
selector: [状态] = "活跃"
# 查找超过 $1000 的订单
selector: [总金额] > 1000
# 按日期范围查找
selector: AND([日期] >= "2024-01-01", [日期] <= "2024-12-31")
# 按名称查找（包含）
selector: CONTAINS([姓名], "Smith")
```
参见 [AppSheet 表达式文档](https://support.google.com/appsheet/topic/10589072) 以获取完整语法。
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `APPSHEET_APP_ID` | 是* | — | 您的 AppSheet 应用 ID |
| `APPSHEET_API_KEY` | 是* | — | 您的 AppSheet API 密钥 |
| `APPSHEET_REGION` | 否 | `global` | API 区域：`global`、`eu`、`apac` |
| `APPSHEET_TABLES` | 否 | — | 以逗号分隔的表名 |
| `APPSHEET_CONFIG_PATH` | 否 | `~/.appsheet-mcp.json` | 多应用配置文件路径 |
| `APPSHEET_DEBUG` | 否 | `false` | 启用调试日志 |
*除非使用配置文件，否则必填。
## 调试
启用调试日志以查看 API 调用：
```bash
export APPSHEET_DEBUG=true
```
调试输出发送到 stderr（stdout 保留用于 MCP 协议）。
## 区域
| 区域 | 基础 URL | 使用于 |
|--------|----------|---------|
| `global` | `www.appsheet.com` | 默认，大多数应用 |
| `eu` | `eu.appsheet.com` | 欧盟数据驻留 |
| `apac` | `asia-southeast.appsheet.com` | 亚太地区 |
## 故障排除
### "AppSheet API 错误（403）"
- 验证您的 API 密钥是否正确
- 确保在 AppSheet 设置 → 集成中启用了 API 访问
- 检查您的 AppSheet 计划是否支持 API 访问（核心或更高）
### "AppSheet API 错误（404）"
- 验证表名是否完全匹配（区分大小写）
- 检查应用 ID 是否正确
### "未找到 AppSheet 配置"
- 设置 `APPSHEET_APP_ID` 和 `APPSHEET_API_KEY` 环境变量
- 或在 `~/.appsheet-mcp.json` 处创建配置文件
## 贡献
欢迎贡献！请在 GitHub 上提出问题或提交 PR。
## 许可证
MIT © [伊斯洛姆·伊尔霍姆](https://github.com/IslomIlkhom) / [反重力](https://antigravity.google/)
