MCP Libsql

🚀 xexr的MCP libSQL

這是一個用於libSQL數據庫操作的模型上下文協議（MCP）服務器，可通過Claude Desktop、Claude Code、Cursor等支持MCP的客戶端實現安全的數據庫訪問。

本項目基於Node運行，使用TypeScript編寫。

🚀 快速開始

安裝

pnpm install -g @xexr/mcp-libsql

本地測試

mcp-libsql --url file:///tmp/test.db --log-mode console

配置Claude Desktop

使用你的Node.js路徑和數據庫URL配置Claude Desktop（請參閱下面的配置示例）。

✨ 主要特性

可用工具

• read-query：執行SELECT查詢，並進行全面的安全驗證。
• write-query：支持事務的INSERT/UPDATE/DELETE操作。
• create-table：帶有安全措施的表創建DDL操作。
• alter-table：表結構修改（ADD/RENAME/DROP操作）。
• list-tables：帶有過濾選項的數據庫元數據瀏覽。
• describe-table：支持多種輸出格式的表結構檢查。

安全與可靠性

• 通過全面的安全驗證實現多層SQL注入防護。
• 具備健康監測和自動重試邏輯的連接池。
• 支持事務，出現錯誤時自動回滾。
• 為滿足安全合規性要求提供全面的審計日誌。

🔐 安全詳情：有關全面的安全特性和測試，請參閱 docs/SECURITY.md。

開發者體驗

• 美觀的表格格式，具備正確的對齊和NULL處理。
• 顯示所有操作的性能指標。
• 提供帶有可操作上下文的清晰錯誤消息。
• 支持參數化查詢，確保數據安全處理。
• 具備增強日誌記錄和熱重載功能的開發模式。

📦 安裝指南

# 使用你選擇的包管理器，例如npm、pnpm、bun等

# 全局安裝
pnpm install -g @xexr/mcp-libsql
mcp-libsql -v # 檢查版本

# ...或者從倉庫構建
git clone https://github.com/Xexr/mcp-libsql.git
cd mcp-libsql
pnpm install # 安裝依賴
pnpm build # 構建項目
node dist/index.js -v  # 檢查版本

💻 使用示例

本地測試

以下假設為全局安裝，若使用本地構建，請將 "mcp-libsql" 替換為 "node dist/index.js"。

# 使用文件數據庫進行測試（默認：僅文件日誌記錄）
mcp-libsql --url file:///tmp/test.db

# 使用HTTP數據庫進行測試
mcp-libsql --url http://127.0.0.1:8080

# 使用Turso數據庫進行測試（環境變量，也可導出環境變量）
LIBSQL_AUTH_TOKEN="your-token" mcp-libsql --url "libsql://your-db.turso.io"

# 使用Turso數據庫進行測試（CLI參數）
mcp-libsql --url "libsql://your-db.turso.io" --auth-token "your-token"

# 開啟開發模式並使用控制檯日誌記錄
mcp-libsql --dev --log-mode console --url file:///tmp/test.db

# 使用不同的日誌記錄模式進行測試
mcp-libsql --url --log-mode both file:///tmp/test.db

Claude Desktop集成

根據你的操作系統在Claude Desktop中配置MCP服務器。

macOS配置

1. 在 ~/Library/Application Support/Claude/claude_desktop_config.json 創建配置文件。

全局安裝

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "file:///Users/username/database.db"
      ]
    }
  }
}

本地構建安裝的替代配置

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "node",
      "args": [
        "/Users/username/projects/mcp-libsql/dist/index.js",
        "--url", 
        "file:///Users/username/database.db"
      ],
    }
  }
}

使用nvm lts版本的Node進行全局安裝的替代配置

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "zsh",
      "args": [
        "-c",
        "source ~/.nvm/nvm.sh && nvm use --lts > /dev/null && mcp-libsql --url file:///Users/username/database.db",
      ],
    }
  }
}

重要提示：建議使用全局安裝方法，因為它會自動處理PATH。

Linux配置

1. 在 ~/.config/Claude/claude_desktop_config.json 創建配置文件。

全局安裝

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "file:///home/username/database.db"
      ]
    }
  }
}

本地構建安裝的替代配置

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "node",
      "args": [
        "/home/username/projects/mcp-libsql/dist/index.js",
        "--url",
        "file:///home/username/database.db"
      ],
    }
  }
}

Windows (WSL2) 配置

1. 在 %APPDATA%\Claude\claude_desktop_config.json 創建配置文件。

全局安裝

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "mcp-libsql --url file:///home/username/database.db",
      ]
    }
  }
}

本地構建安裝的替代配置

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "/home/username/projects/mcp-libsql/dist/index.js --url file:///home/username/database.db",
      ]
    }
  }
}

使用nvm管理Node進行全局安裝的替代配置

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "source ~/.nvm/nvm.sh && mcp-libsql --url file:///home/username/database.db",
      ]
    }
  }
}

重要提示：使用 wsl.exe -e（而不僅僅是 wsl.exe）以確保正確處理命令，並避免Windows上服務器命令接收出現問題。

數據庫認證

對於Turso（以及其他需要憑證的）數據庫，你需要一個認證令牌。有兩種安全的提供方式：

以下展示的是全局安裝的情況，請根據你的設置進行相應調整。

方法1：環境變量（推薦）

使用環境變量配置Claude Desktop（macOS/Linux示例）

export LIBSQL_AUTH_TOKEN="your-turso-auth-token-here"

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "libsql://your-database.turso.io"
      ]
    }
  }
}

方法2：CLI參數

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "libsql://your-database.turso.io",
        "--auth-token",
        "your-turso-auth-token-here"
      ]
    }
  }
}

獲取Turso認證令牌

1. 安裝Turso CLI

   curl -sSfL https://get.tur.so/install.sh | bash
   

2. 登錄Turso

   turso auth login
   

3. 創建認證令牌

   turso auth token create --name "mcp-libsql"
   

4. 獲取數據庫URL

   turso db show your-database-name --url
   

安全最佳實踐

• 環境變量比CLI參數更安全（令牌不會出現在進程列表中）。
• MCP配置文件可能包含令牌 - 確保它們不會提交到版本控制中。
• 考慮在生產環境中使用外部密鑰管理。
• 使用具有最小必要權限的作用域令牌。
• 定期輪換令牌以增強安全性。
• 通過Turso儀表板監控令牌使用情況。

示例：完整的Turso設置

1. 創建並配置數據庫

   # 創建數據庫
   turso db create my-app-db
   
   # 獲取數據庫URL
   turso db show my-app-db --url
   # 輸出: libsql://my-app-db-username.turso.io
   
   # 創建認證令牌
   turso auth token create --name "mcp-libsql-token"
   # 輸出: your-long-auth-token-string
   

2. 配置Claude Desktop

   export LIBSQL_AUTH_TOKEN="your-turso-auth-token-here"
   

   {
     "mcpServers": {
       "mcp-libsql": {
         "command": "mcp-libsql",
         "args": [
           "--url",
           "libsql://my-app-db-username.turso.io"
         ]
       }
     }
   }
   

3. 測試連接

   # 先進行本地測試
   mcp-libsql --url "libsql://my-app-db-username.turso.io" --log-mode console
   

配置注意事項

• 文件路徑：使用絕對路徑以避免路徑解析問題。
• 數據庫URL：
  • 文件數據庫：file:///absolute/path/to/database.db
  • HTTP數據庫：http://hostname:port
  • libSQL/Turso：libsql://your-database.turso.io
• Node.js路徑：使用 which node 查找你的Node.js安裝路徑。
• 工作目錄：設置 cwd 以確保相對路徑正常工作。
• 認證：對於Turso數據庫，使用環境變量安全處理令牌。
• 日誌記錄模式：
  • 默認 file 模式可防止MCP協議中出現JSON解析錯誤。
  • 使用 --log-mode console 進行開發調試。
  • 使用 --log-mode both 進行全面日誌記錄。
  • 使用 --log-mode none 禁用所有日誌記錄。

2. 更新配置後完全重啟Claude Desktop。

3. 通過要求Claude運行SQL查詢來測試集成

   Can you run this SQL query: SELECT 1 as test
   

📚 詳細文檔

可用工具

• read-query - 執行帶有安全驗證的SELECT查詢。
• write-query - 支持事務的INSERT/UPDATE/DELETE操作。
• create-table - 帶有DDL安全的CREATE TABLE操作。
• alter-table - 修改表結構（ADD/RENAME/DROP）。
• list-tables - 瀏覽數據庫元數據和對象。
• describe-table - 檢查表架構和結構。

📖 詳細API文檔：有關完整的輸入/輸出示例和參數，請參閱 docs/API.md。

🔧 技術細節

測試

# 運行所有測試
pnpm test

# 以監視模式運行測試
pnpm test:watch

# 運行帶覆蓋率的測試
pnpm test:coverage

# 運行特定測試文件
pnpm test security-verification

# 代碼檢查
pnpm lint

# 修復代碼檢查問題
pnpm lint:fix

# 類型檢查
pnpm typecheck

測試覆蓋率：403個測試覆蓋了所有功能，包括邊緣情況、錯誤場景、CLI參數、認證和全面的安全驗證。

常見問題

1. 構建失敗

# 清理並重新構建
rm -rf dist node_modules
pnpm install && pnpm build

2. Node.js版本問題（macOS）

SyntaxError: Unexpected token '??='

問題：Claude Desktop可能默認使用系統中較舊的Node.js版本，該版本不支持所需的功能集。

解決方案：使用上述的全局安裝和nvm選擇Node版本的方法。

3. 服務器無法啟動

• 全局安裝：pnpm install -g @xexr/mcp-libsql
• 本地安裝：確保已運行 pnpm build 且 dist/index.js 存在。
• 本地測試：mcp-libsql --url file:///tmp/test.db
• 配置更改後重啟Claude Desktop。

4. 工具不可用

• 驗證數據庫URL是否可訪問。
• 檢查Claude Desktop日誌中的連接錯誤。
• 使用簡單的文件數據庫進行測試：file:///tmp/test.db。

5. JSON解析錯誤（已解決）

Expected ',' or ']' after array element in JSON

已解決：此問題由stdout控制檯日誌記錄引起。--log-mode 選項現在默認使用 file 模式，可防止此問題。如果你看到這些錯誤，請確保使用默認的 --log-mode file 或根本不指定 --log-mode。注意，此錯誤無害，如果你希望使用控制檯日誌記錄，工具仍然可以正常工作。

6. 數據庫連接問題

# 測試數據庫連接性
sqlite3 /tmp/test.db "SELECT 1"

# 修復權限
chmod 644 /path/to/database.db

🔧 完整的故障排除指南：有關所有問題的詳細解決方案，請參閱 docs/TROUBLESHOOTING.md。

架構

基於TypeScript和現代Node.js模式構建：

• 具備健康監測和重試邏輯的連接池。
• 具有一致驗證和錯誤處理的基於工具的架構。
• 採用多層輸入驗證的安全優先設計。
• 覆蓋所有場景的244個測試的全面測試。

貢獻

1. 遵循TypeScript嚴格模式和現有代碼模式。
2. 為新功能編寫測試。
3. 維護安全措施。
4. 更新文檔。

開發：pnpm dev • 構建：pnpm build • 測試：pnpm test

📄 許可證

本項目採用MIT許可證 - 有關詳細信息，請參閱 LICENSE 文件。

🔗 鏈接

• 模型上下文協議
• MCP TypeScript SDK
• libSQL文檔
• Claude Desktop