mcp-turso-cloud

mcp-turso-cloud

一个为大模型提供 Turso 数据库集成能力的模型上下文协议（MCP）服务。该服务采用两级身份验证系统，处理组织级和数据库级操作，方便直接通过大模型管理和查询 Turso 数据库。

功能

🏢 组织级操作

• 列出数据库：查看 Turso 组织中的所有数据库
• 创建数据库：使用可自定义选项创建新数据库
• 删除数据库：从组织中移除数据库
• 生成数据库令牌：为特定数据库创建身份验证令牌

💾 数据库级操作

• 列出表：查看特定数据库中的所有表
• 执行只读查询：运行 SELECT 和 PRAGMA 查询（只读操作）
• 执行查询：运行可能具有破坏性的 SQL 查询（INSERT、UPDATE、DELETE 等）
• 描述表：获取数据库表的架构信息
• 向量搜索：使用 SQLite 向量扩展执行向量相似性搜索

⚠️ 重要：查询执行安全性 ⚠️

该服务通过区分只读数据库操作和具有破坏性的数据库操作来保障安全：

• 使用 execute_read_only_query 执行 SELECT、只读 WITH/VALUES、读取操作的 EXPLAIN，以及允许列表中的元数据 PRAGMA。
• 使用 execute_query 执行 INSERT、UPDATE、DELETE、CREATE、DROP、修改数据的 PRAGMA，以及其他会修改数据的操作。

只读工具始终请求只读 Turso 凭据，即使已缓存具有完全访问权限的客户端也是如此。令牌端点会将 authorization=read-only 作为查询参数接收。读取失败时绝不会回退到完全访问权限。令牌和客户端会根据权限分别缓存，并在令牌过期时刷新。

本地 SQL 验证会拒绝多条语句、只读路径上的修改数据型 PRAGMA，以及文件/扩展函数。这是一项保守的路由检查，并非完整的 SQL 解析器，也不能替代 Turso 的服务端授权。未知或带引号的 PRAGMA 名称必须使用写入工具。不支持包含内部分号的复合语句（例如触发器定义）。生成的 SQL 中，标识符会加引号；数据值则使用绑定参数。

这种区分支持不同的权限级别和审批要求：

• 在许多场景中，只读操作可以自动批准
• 为保障安全，具有破坏性的操作可以要求明确审批

批准 SQL 查询前，务必仔细阅读并检查！ 对于可能修改或删除数据的破坏性操作，这一点尤为重要。请花时间了解每条查询的作用，再允许其执行。

两级身份验证系统

该服务采用了完善的身份验证系统：

1. 组织级身份验证

   • 使用 Turso Platform API 令牌
   • 管理数据库和组织级操作
   • 从 Turso 控制台获取

2. 数据库级身份验证

   • 使用数据库专属令牌
   • 使用组织令牌自动生成
   • 为提高性能而缓存，并在需要时轮换

配置

此服务需要通过 MCP 客户端进行配置。以下是不同环境的配置示例：

Cline/Claude Desktop 配置

将以下内容添加到 Cline/Claude Desktop MCP 设置中：

{
	"mcpServers": {
		"mcp-turso-cloud": {
			"command": "npx",
			"args": ["-y", "mcp-turso-cloud"],
			"env": {
				"TURSO_API_TOKEN": "your-turso-api-token",
				"TURSO_ORGANIZATION": "your-organization-name",
				"TURSO_DEFAULT_DATABASE": "optional-default-database"
			}
		}
	}
}

使用 WSL 的 Claude Desktop 配置

对于 WSL 环境，将以下内容添加到 Claude Desktop 配置中：

{
	"mcpServers": {
		"mcp-turso-cloud": {
			"command": "wsl.exe",
			"args": [
				"bash",
				"-c",
				"TURSO_API_TOKEN=your-token TURSO_ORGANIZATION=your-org node /path/to/mcp-turso-cloud/dist/index.js"
			]
		}
	}
}

环境变量

该服务需要以下环境变量：

• TURSO_API_TOKEN：你的 Turso Platform API 令牌（必填）
• TURSO_ORGANIZATION：你的 Turso 组织名称（必填）
• TURSO_DEFAULT_DATABASE：未指定数据库时使用的默认数据库（可选）
• TOKEN_EXPIRATION：生成的数据库令牌的过期时间（可选，默认值：'7d'）
• TOKEN_PERMISSION：生成的令牌的权限级别（可选，默认值：'full-access'）

API

该服务按类别实现了 MCP 工具：

组织工具

list_databases

列出 Turso 组织中的所有数据库。

参数：

• limit（整数，可选）：最大结果数，默认值为 1000，最大值为 10000
• offset（整数，可选）：要跳过的结果数，默认值为 0，最大值为 1000000

响应包含 pagination，其中有 returned_count、has_more 和 next_offset。

示例响应：

{
	"databases": [
		{
			"name": "customer_db",
			"id": "abc123",
			"region": "us-east",
			"created_at": "2023-01-15T12:00:00Z"
		},
		{
			"name": "product_db",
			"id": "def456",
			"region": "eu-west",
			"created_at": "2023-02-20T15:30:00Z"
		}
	]
}

create_database

在组织中创建新数据库。

参数：

• name（字符串，必填）：新数据库的名称
• group（字符串，可选）：要分配给数据库的组
• regions（字符串数组，可选）：部署数据库的区域

示例：

{
	"name": "analytics_db",
	"group": "production",
	"regions": ["us-east", "eu-west"]
}

delete_database

删除组织中的数据库。

参数：

• name（字符串，必填）：要删除的数据库名称

示例：

{
	"name": "test_db"
}

generate_database_token

为指定数据库生成新令牌。过期时间通过 TOKEN_EXPIRATION 配置；返回的 JWT 是机密信息。

参数：

• database（字符串，必填）：数据库名称
• permission（字符串，可选）：权限级别（'full-access' 或 'read-only'）

示例：

{
	"database": "customer_db",
	"permission": "read-only"
}

数据库工具

数据库名称限 1–64 个字母、数字、下划线或连字符。表和列标识符接受 1–64 个字符（不包括空字节）；标点符号和引号会安全转义。只有操作成功后，指定的数据库才会成为当前上下文。

list_tables

列出数据库中的所有表，并附带分页元数据。

参数：

• database（字符串，可选）：数据库名称（未提供时使用上下文）
• limit（整数，可选）：最大结果数，默认值为 1000，最大值为 10000
• offset（整数，可选）：要跳过的结果数，默认值为 0，最大值为 1000000

示例：

{
	"database": "customer_db"
}

execute_read_only_query

对数据库执行一条 SELECT 查询、只读 WITH/VALUES 查询、读取操作的 EXPLAIN，或允许列表中的元数据 PRAGMA。

参数：

• query（字符串，必填）：一条 SQL 语句，最多 10000 个字符
• params（对象，可选）：命名参数，或从 "1" 开始且连续的位置参数键；值必须是字符串、有限数值、布尔值或 null
• database（字符串，可选）：数据库名称（未提供时使用上下文）
• limit（整数，可选）：最大行数，默认值为 1000，最大值为 10000
• offset（整数，可选）：要跳过的行数，默认值为 0，最大值为 1000000

SELECT 样式的查询会在外层套用 limit/offset，同时保留 SQL 中已有的 limit。元数据 PRAGMA 和 EXPLAIN 的结果会在获取后进行切片。分页时请使用稳定的 ORDER BY。响应会保留 result.rows，并添加 pagination 元数据。

查询结果行和列名的 JSON 大小上限为 512 KiB。如果某行无法放入，请选择更少或更小的列（例如，使用 substr）。result.truncated 和 truncation_reason 会说明省略的结果；如果没有行符合大小限制，next_offset 为 null。BigInt 会转换为十进制字符串，blob 则表示为 { "type": "blob", "base64": "..." }。

示例：

{
	"query": "SELECT * FROM users WHERE age > ?",
	"params": { "1": 21 },
	"database": "customer_db"
}

execute_query

针对数据库执行可能具有破坏性的 SQL 查询（INSERT、UPDATE、DELETE、 CREATE 等）。

参数：

• query（字符串，必填）：一条写入语句，最多 10000 个字符；包括会修改数据的 PRAGMA 和以 WITH 开头的写入语句
• params（对象，可选）：与读取工具相同的参数类型
• database（字符串，可选）：数据库名称（未提供时使用上下文）

示例：

{
	"query": "INSERT INTO users (name, age) VALUES (?, ?)",
	"params": { "1": "Alice", "2": 30 },
	"database": "customer_db"
}

写入结果行（例如 RETURNING）最多返回 1000 行，且受相同的字节数限制。 rowsAffected 保持不变。截断不会撤销写入：不要为了获取省略的行而重新执行写入。

describe_table

获取表的架构信息。

参数：

• table（字符串，必填）：表名
• database（字符串，可选）：数据库名称（未提供时使用上下文）

示例：

{
	"table": "users",
	"database": "customer_db"
}

vector_search

使用 SQLite 向量扩展执行向量相似度搜索。

参数：

• table（字符串，必填）：表名
• vector_column（字符串，必填）：包含向量的列
• query_vector（number[]，必填）：1–4096 个有限数值
• limit（整数，可选）：最大结果数，默认为 10，最大为 1000
• database（字符串，可选）：数据库名称（未提供时使用上下文）

示例：

{
	"table": "embeddings",
	"vector_column": "embedding",
	"query_vector": [0.1, 0.2, 0.3, 0.4],
	"limit": 5,
	"database": "vector_db"
}

开发

设置

使用 Node.js 24.15.0 或更高版本，以及 pnpm 12.5.1（固定在 package.json 中）。.node-version 用于选择开发运行时。

pnpm install
pnpm check
pnpm test

Vite+ 通过 vite.config.ts 提供构建、格式化、lint、类型检查和测试运行器：

• pnpm build — 将可执行文件和声明打包到 dist/
• pnpm start — 使用你的 Turso 配置运行已构建的服务
• pnpm dev — 在源代码变更时重新构建
• pnpm inspect — 使用已构建的服务打开 MCP 检查器
• pnpm check — 检查格式、lint 和类型
• pnpm check:fix — 应用格式化和安全的 lint 修复
• pnpm format / pnpm format:check — 格式化或检查格式
• pnpm test — 构建并运行离线 SQL、权限、令牌、MCP 处理程序和 CLI 测试；无需 Turso 凭据或访问实时数据库。 SQL 执行测试使用隔离的内存 libSQL 数据库。

依赖项版本位于 pnpm-workspace.yaml 的目录中。新版本必须发布至少两天后才能安装。

编辑器

在 Zed 中安装 Oxc 扩展，或在 VS Code 中安装 Vite Plus Extension Pack。已提交的 .zed/settings.json 和 .vscode/settings.json 使用 Oxfmt，并采用共享的 vite.config.ts 格式设置。不再使用 Prettier 配置。

发布

pnpm changeset
pnpm version
pnpm check
pnpm test
pnpm release

pnpm release 通过 Changesets 构建并发布。pnpm pack 可在本地验证软件包，而无需发布。

故障排除

API 令牌问题

如果遇到身份验证错误：

1. 确认你的 Turso API 令牌有效且具有必要的权限
2. 检查组织名称是否正确
3. 确认令牌尚未过期

数据库连接问题

如果连接数据库时遇到问题：

1. 确认数据库存在于你的组织中
2. 检查你的 API 令牌是否有权访问该数据库
3. 确认数据库名称拼写正确

贡献

欢迎贡献！欢迎提交 Pull Request。

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

基于以下项目构建：

• Model Context Protocol
• Turso Database
• libSQL