# Turso MCP Server

A Model Context Protocol (MCP) server for [Turso](https://turso.tech) (libSQL) database access.

## Features

- Execute SQL queries (SELECT, INSERT, UPDATE, DELETE)
- List all tables in your database
- Describe table schemas
- Retrieve table data with pagination
- Full parameterized query support

## Installation

```bash
npm install -g @gamzadongza/turso-mcp-server
```

## Configuration

### Environment Variables

You need to set these environment variables:

- `TURSO_DATABASE_URL`: Your Turso database URL (e.g., `libsql://your-db.turso.io`)
- `TURSO_AUTH_TOKEN`: Your Turso authentication token

### Getting Turso Credentials

1. Install Turso CLI:
```bash
# Windows (PowerShell)
irm https://get.tur.so/install.ps1 | iex

# macOS/Linux
curl -sSfL https://get.tur.so/install.sh | bash
```

2. Login and create database:
```bash
turso auth login
turso db create my-database
```

3. Get your credentials:
```bash
# Get database URL
turso db show my-database --url

# Create auth token
turso db tokens create my-database
```

## Usage with Claude Desktop

Add this to your Claude Desktop config:

### macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
### Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "turso": {
      "command": "turso-mcp-server",
      "env": {
        "TURSO_DATABASE_URL": "libsql://your-db.turso.io",
        "TURSO_AUTH_TOKEN": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
      }
    }
  }
}
```

## Usage with Claude Mobile (Android/iOS)

1. Go to Claude app settings
2. Add MCP server from Smithery: `@gamzadongza/turso-mcp-server`
3. Set environment variables:
   - `TURSO_DATABASE_URL`: Your database URL
   - `TURSO_AUTH_TOKEN`: Your auth token

## Available Tools

### `execute_query`
Execute any SQL query on your Turso database.

**Parameters:**
- `query` (string, required): SQL query to execute
- `params` (array, optional): Parameters for parameterized queries

**Example:**
```sql
SELECT * FROM users WHERE age > ?
```

### `list_tables`
Get a list of all tables in your database.

**Example:**
"Show me all tables in my database"

### `describe_table`
Get detailed schema information about a specific table.

**Parameters:**
- `table_name` (string, required): Name of the table

**Example:**
"Describe the structure of the users table"

### `get_table_data`
Retrieve data from a table with pagination support.

**Parameters:**
- `table_name` (string, required): Name of the table
- `limit` (number, optional): Max rows to return (default: 100, max: 1000)
- `offset` (number, optional): Rows to skip (default: 0)

**Example:**
"Get the first 50 rows from the posts table"

## Development

```bash
# Clone and install dependencies
git clone https://github.com/gamzadongza/turso-mcp-server
cd turso-mcp-server
npm install

# Build
npm run build

# Run locally
export TURSO_DATABASE_URL="libsql://your-db.turso.io"
export TURSO_AUTH_TOKEN="your-token"
node dist/index.js
```

## License

MIT

## Links

- [Turso](https://turso.tech)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP Servers](https://github.com/modelcontextprotocol/servers)