mcp-turso-cloud

一个提供与Turso数据库集成的模型上下文协议（MCP）服务器，专为大型语言模型（LLMs）设计。该服务器实现了两级认证系统，可同时处理组织级和数据库级操作，使您能够直接从LLMs轻松管理和查询Turso数据库。

功能特性

🏢 组织级操作

列出数据库：查看您Turso组织中的所有数据库
创建数据库：使用可定制选项创建新数据库
删除数据库：从您的组织中移除数据库
生成数据库令牌：为特定数据库创建认证令牌

💾 数据库级操作

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

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

该服务器实现了注重安全的只读操作与破坏性数据库操作分离机制：

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

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

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

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

两级认证系统

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

组织级认证
- 使用Turso平台API令牌
- 管理数据库和组织级操作
- 通过Turso仪表板获取
数据库级认证
- 使用特定于数据库的令牌
- 使用组织令牌自动生成
- 为提高性能而缓存，并根据需要轮换

配置

该服务器需要通过您的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平台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"
}

开发

设置

克隆仓库
安装依赖：

npm install

构建项目：

npm run build

以开发模式运行：

npm run dev

发布

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

npm run build

发布到npm：

npm publish

故障排除

API令牌问题

如果遇到认证错误：

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

数据库连接问题

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

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

贡献

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

许可证

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

致谢

基于以下项目构建：