mcp-turso-cloud

一个提供与Turso数据库集成的模型上下文协议（MCP）服务器，适用于大型语言模型（LLMs）。该服务器实现了一个两级认证系统，用于处理组织级和数据库级操作，使得可以直接从LLMs管理和查询Turso数据库变得容易。

<a href="https://glama.ai/mcp/servers/hnkzlqoh92"> <img width="380" height="200" src="https://gips3.baidu.com/it/u=2392738860,2594799454&fm=3081&app=3081&f=PNG?w=760&h=400" alt="mcp-turso-cloud MCP服务器" /> </a>

功能

🏢 组织级操作

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

💾 数据库级操作

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

⚠️ 重要提示：查询执行安全 ⚠️

此服务器实现了针对只读和破坏性数据库操作的安全分离：

• 使用execute_read_only_query进行SELECT和PRAGMA查询（安全，只读操作）
• 使用execute_query进行INSERT、UPDATE、DELETE、CREATE、DROP和其他修改数据的操作

这种分离允许不同的权限级别和审批需求：

• 在许多情况下，只读操作可以自动批准
• 破坏性操作可能需要明确的批准以确保安全

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

两级认证系统

服务器实现了一个复杂的认证系统：

1. 组织级认证

   • 使用Turso平台API令牌
   • 管理数据库和组织级操作
   • 通过Turso仪表板获得

2. 数据库级认证

   • 使用特定于数据库的令牌
   • 自动使用组织令牌生成
   • 为了性能而缓存，并根据需要旋转

配置

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

Cline/Claude桌面配置

将以下内容添加到您的Cline/Claude桌面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"
			}
		}
	}
}

Claude桌面与WSL配置

对于WSL环境，将以下内容添加到您的Claude桌面配置中：

{
	"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平台API令牌（必需）
• TURSO_ORGANIZATION：您的Turso组织名称（必需）
• TURSO_DEFAULT_DATABASE：未指定时使用的默认数据库（可选）
• TOKEN_EXPIRATION：生成的数据库令牌的过期时间（可选，默认值：'7d'）
• TOKEN_PERMISSION：生成令牌的权限级别（可选，默认值：'full-access'）

API

服务器实现了按类别组织的MCP工具：

组织工具

list_databases

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

参数：无

示例响应：

{
	"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

为特定数据库生成新的令牌。

参数：

• database（字符串，必需）：数据库名称
• expiration（字符串，可选）：令牌过期时间
• permission（字符串，可选）：权限级别（'full-access'或'read-only'）

示例：

{
	"database": "customer_db",
	"expiration": "30d",
	"permission": "read-only"
}

数据库工具

list_tables

列出数据库中的所有表。

参数：

• database（字符串，可选）：数据库名称（如果未提供，则使用上下文）

示例：

{
	"database": "customer_db"
}

execute_read_only_query

对数据库执行只读SQL查询（SELECT、PRAGMA）。

参数：

• query（字符串，必需）：要执行的SQL查询（必须是SELECT或PRAGMA）
• params（对象，可选）：查询参数
• database（字符串，可选）：数据库名称（如果未提供，则使用上下文）

示例：

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

execute_query

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

参数：

• query（字符串，必需）：要执行的SQL查询（不能是SELECT或PRAGMA）
• params（对象，可选）：查询参数
• database（字符串，可选）：数据库名称（如果未提供，则使用上下文）

示例：

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

describe_table

获取表的模式信息。

参数：

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

示例：

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

vector_search

使用SQLite向量扩展进行向量相似性搜索。

参数：

• table（字符串，必需）：表名称
• vector_column（字符串，必需）：包含向量的列
• query_vector（数字数组，必需）：用于相似性搜索的查询向量
• limit（数字，可选）：结果的最大数量（默认值：10）
• database（字符串，可选）：数据库名称（如果未提供，则使用上下文）

示例：

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

开发

设置

1. 克隆仓库
2. 安装依赖项：

npm install

3. 构建项目：

npm run build

4. 在开发模式下运行：

npm run dev

发布

1. 更新package.json中的版本
2. 构建项目：

npm run build

3. 发布到npm：

npm publish

故障排除

API令牌问题

如果您遇到身份验证错误：

1. 验证您的Turso API令牌有效且具有必要的权限
2. 检查您的组织名称是否正确
3. 确保您的令牌没有过期

数据库连接问题

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

1. 验证数据库存在于您的组织中
2. 检查您的API令牌是否有访问数据库的权限
3. 确保数据库名称拼写正确

贡献

欢迎贡献！请随时提交Pull Request。

许可证

MIT许可证 - 详情见LICENSE文件。

致谢

基于：

• 模型上下文协议
• Turso数据库
• libSQL