Baserow MCP Server

Baserow MCP 服务

一个 MCP（Model Context Protocol）服务，可在兼容 MCP 的客户端（Claude Desktop、Cursor、Windsurf 等）与 Baserow 之间实现无缝集成，通过自然语言执行 AI 驱动的数据库操作。

🚀 功能

• 🔐 智能身份验证：使用凭据自动刷新令牌，或手动使用 JWT/数据库令牌
• 🏢 工作区管理：列出、创建和管理 Baserow 工作区
• 🗄️ 数据库操作：全面控制工作区中的数据库
• 📊 表管理：创建、列出和管理表及其字段定义
• 📝 行的 CRUD 操作：完整支持创建、读取、更新和删除
• ⚡ 批量操作：高效批量创建、更新和删除行
• 🔍 高级查询：支持分页、筛选和排序
• 💡 自然语言：使用普通英语与数据库交互

📋 前提条件

• Node.js v22+（通过 nvm 安装）
• 兼容 MCP 的客户端：
  • Claude Desktop
  • Cursor
  • Windsurf
  • 其他任何兼容 MCP 的 AI 编辑器
• Baserow 账户（可自托管或使用云服务）

🛠️ 安装

1. 克隆代码库：

   git clone https://github.com/ayyazzafar/mcp-baserow.git
   cd mcp-baserow
   

2. 安装依赖项：

   npm install
   

3. 配置身份验证：

   cp .env.example .env
   

   编辑 .env 并添加你的凭据：

   # Recommended: Use credentials for automatic token refresh
   [email protected]
   BASEROW_PASSWORD=your_password
   
   # Optional: Override default API URL for self-hosted instances
   # BASEROW_API_URL=https://your-baserow-instance.com
   

4. 构建项目：

   npm run build
   

🔑 身份验证选项

选项 1：用户名/密码（推荐）

自动刷新令牌并提供完整的 API 访问权限：

[email protected]
BASEROW_PASSWORD=your_password

选项 2：JWT 令牌

用于手动管理令牌（60 分钟后过期）：

BASEROW_API_TOKEN=JWT_your_jwt_token_here

选项 3：数据库令牌

用于特定数据库的操作（权限范围有限，永不过期）：

BASEROW_API_TOKEN=Token_your_database_token_here

⚙️ 配置

MCP 客户端设置

Claude Desktop

1. 打开配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 添加 Baserow 服务：

   {
     "mcpServers": {
       "baserow": {
         "command": "/path/to/mcp-baserow/start.sh"
       }
     }
   }
   

Cursor

1. 打开 Cursor 设置
2. 前往 MCP 服务部分
3. 添加：

   {
     "baserow": {
       "command": "/path/to/mcp-baserow/start.sh"
     }
   }
   

Windsurf

1. 打开 Windsurf 配置
2. 添加到 MCP 服务：

   {
     "baserow": {
       "command": "/path/to/mcp-baserow/start.sh"
     }
   }
   

3. 重启 MCP 客户端

📚 使用示例

自然语言指令

配置完成后，你可以在 MCP 客户端中使用自然语言：

• “显示我所有的 Baserow 工作区”
• “在我的工作区中创建一个名为 ‘Project Tracker’ 的新数据库”
• “列出 Project Tracker 数据库中的所有表”
• “在 Tasks 表中添加一行，标题为 ‘Review PR’，状态为 ‘In Progress’”
• “更新 Tasks 表中的第 5 行，将其标记为已完成”
• “删除 Archive 表中所有超过 30 天的行”

可用的 MCP 工具

身份验证工具（3）

• baserow_auth_status - 检查身份验证状态和功能
• baserow_auth_login - 使用凭据登录
• baserow_auth_set_token - 手动设置 JWT 或数据库令牌

工作区工具（4）

• baserow_list_workspaces - 列出所有工作区
• baserow_get_workspace - 获取工作区详情
• baserow_create_workspace - 创建新工作区
• baserow_set_workspace - 设置操作的活动工作区

数据库工具（3）

• baserow_list_databases - 列出工作区中的数据库
• baserow_get_database - 获取数据库详情
• baserow_create_database - 创建新数据库

表工具（3）

• baserow_list_tables - 列出数据库中的表
• baserow_get_table - 获取表及其字段定义
• baserow_create_table - 创建新表

行操作（8）

• baserow_list_rows - 使用分页和筛选列出行
• baserow_get_row - 根据 ID 获取单行
• baserow_create_row - 创建新行
• baserow_update_row - 更新现有行
• baserow_delete_row - 删除行
• baserow_batch_create_rows - 创建多行
• baserow_batch_update_rows - 更新多行
• baserow_batch_delete_rows - 删除多行

🧪 开发

设置开发环境

# Install dependencies
npm install

# Run TypeScript compiler in watch mode
npm run dev

# Run tests (when available)
npm test

项目结构

mcp-baserow/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── auth-manager.ts   # Authentication handling
│   ├── baserow-client.ts # Baserow API client
│   ├── tools/           # MCP tool implementations
│   │   ├── auth.ts      # Authentication tools
│   │   ├── workspace.ts # Workspace operations
│   │   ├── database.ts  # Database operations
│   │   ├── table.ts     # Table operations
│   │   └── row.ts       # Row CRUD operations
│   └── types/           # TypeScript type definitions
├── dist/                # Compiled JavaScript
├── examples/            # Usage examples
└── tests/              # Test files

🤝 参与贡献

欢迎贡献！详情请参阅贡献指南。

贡献者快速入门

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 创建 Pull Request

📝 更新日志

请参阅 CHANGELOG.md，了解各版本的更改列表。

🐛 故障排除

常见问题

1. “身份验证失败”

   • 检查 .env 中的凭据
   • 确保你的 Baserow 账户处于活动状态
   • 检查是否使用了正确的 API URL

2. “未提供 workspace_id”

   • 使用 baserow_set_workspace 设置活动工作区
   • 或在数据库操作中提供 workspace_id 参数

3. “服务已断开连接”

   • 检查 MCP 客户端的日志：
     • Claude Desktop：~/Library/Logs/Claude/mcp-server-baserow.log
     • 其他客户端：检查各自的日志位置
   • 确保已安装 Node.js v22+
   • 确认已安装所有依赖项

调试模式

通过设置以下内容启用调试日志：

export DEBUG=baserow:*

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🙏 致谢

• 感谢 Anthropic 制定 MCP 规范
• 感谢 Baserow 提供出色的开源数据库平台
• 感谢 MCP 社区分享示例和最佳实践

🔗 链接

• MCP 文档
• Baserow API 文档
• 报告问题

---

由开源社区用 ❤️ 打造