mcp-turso-cloud

这是一个 Model Context Protocol (MCP) 服务器，为 LLMs 提供与 Turso 数据库的集成。该服务器实现了一个两级认证系统，以处理组织级别和数据库级别的操作，从而方便地直接从 LLMs 管理和查询 Turso 数据库。

功能

🏢 组织级别操作

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

💾 数据库级别操作

• 列出表：查看特定数据库中的所有表
• 执行查询：对您的数据库运行 SQL 查询
• 描述表：获取数据库表的模式信息
• 向量搜索：使用 SQLite 向量扩展执行向量相似性搜索

两级认证系统

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

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_query

对数据库执行 SQL 查询。

参数：

• query (字符串, 必填): 要执行的 SQL 查询
• params (对象, 可选): 查询参数
• database (字符串, 可选): 数据库名称（如果未提供则使用上下文）

示例：

{
    "query": "SELECT * FROM users WHERE age > ?",
    "params": { "1": 21 },
    "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

1. 构建项目：

npm run build

1. 以开发模式运行：

npm run dev

发布

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

npm run build

1. 发布到 npm：

npm publish

故障排除

API 令牌问题

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

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

数据库连接问题

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

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

贡献

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

许可

MIT 许可 - 查看 LICENSE 文件以获取详细信息。

致谢

基于以下构建：

• Model Context Protocol
• Turso Database
• libSQL