A Model Context Protocol (MCP) server that provides integration with
Turso databases for LLMs. This server implements a two-level
authentication system to handle both organization-level and
database-level operations, making it easy to manage and query Turso
databases directly from LLMs.
🗂️ A Model Context Protocol (MCP) server that provides integration with Turso databases for LLMs. This server implements a two-level authentication system to handle both organization-level and database-level operations, making it easy to manage and query Turso databases directly from LLMs.
Describe Table: Get schema information for database tables
Vector Search: Perform vector similarity search using SQLite
vector extensions
⚠️ IMPORTANT: Query Execution Security ⚠️
This server implements a security-focused separation between read-only
and destructive database operations:
Use execute_read_only_query for SELECT, read-only WITH/VALUES,
EXPLAIN of reads, and allowlisted metadata PRAGMAs.
Use execute_query for INSERT, UPDATE, DELETE, CREATE, DROP,
mutating PRAGMAs, and other operations that modify data.
Read tools always request read-only Turso credentials, including when
full-access clients are already cached. The token endpoint receives
authorization=read-only
as a query parameter. Read failures never fall back to full access.
Tokens and clients are cached separately by permission and refreshed
when tokens expire.
Local SQL validation rejects multiple statements, mutating PRAGMAs on
the read path, and file/extension functions. It is a conservative
routing check, not a complete SQL parser or a substitute for Turso's
server-side authorization. Unknown or quoted PRAGMA names require the
write tool. Compound statements containing internal semicolons (such
as trigger definitions) are not supported. Identifiers in generated
SQL are quoted; data values use bindings.
This separation allows for different permission levels and approval
requirements:
Read-only operations can be auto-approved in many contexts
Destructive operations can require explicit approval for safety
ALWAYS CAREFULLY READ AND REVIEW SQL QUERIES BEFORE APPROVING
THEM! This is especially critical for destructive operations that
can modify or delete data. Take time to understand what each query
does before allowing it to execute.
Two-Level Authentication System
The server implements a sophisticated authentication system:
Organization-Level Authentication
Uses a Turso Platform API token
Manages databases and organization-level operations
Obtained through the Turso dashboard
Database-Level Authentication
Uses database-specific tokens
Generated automatically using the organization token
Cached for performance and rotated as needed
Configuration
This server requires configuration through your MCP client. Here are
examples for different environments:
Cline/Claude Desktop Configuration
Add this to your Cline/Claude Desktop MCP settings:
Database names are limited to 1–64 letters, digits, underscores, or
hyphens. Table/column identifiers accept 1–64 characters, excluding
null bytes; punctuation and quotes are safely escaped. A supplied
database becomes the current context only after its operation
succeeds.
list_tables
Lists all tables in a database, with pagination metadata.
Parameters:
database (string, optional): Database name (uses context if not
provided)
limit (integer, optional): Maximum results, default 1000, maximum
10000
offset (integer, optional): Results to skip, default 0, maximum
1000000
Example:
{
"database": "customer_db"
}
execute_read_only_query
Executes one SELECT, read-only WITH/VALUES query, EXPLAIN of a read,
or allowlisted metadata PRAGMA against a database.
Parameters:
query (string, required): One SQL statement, maximum 10000
characters
params (object, optional): Named parameters or contiguous
positional keys starting at "1"; values must be strings, finite
numbers, booleans, or null
database (string, optional): Database name (uses context if not
provided)
limit (integer, optional): Maximum rows, default 1000, maximum
10000
offset (integer, optional): Rows to skip, default 0, maximum
1000000
SELECT-style queries are wrapped with an outer limit/offset,
preserving any limit already present in your SQL. Metadata PRAGMA and
EXPLAIN results are sliced after fetching. Use a stable ORDER BY
when paging. Responses retain result.rows and add pagination
metadata.
Query result rows and column names have a 512 KiB JSON budget. If a
row cannot fit, select fewer/smaller columns (for example, substr).
result.truncated and truncation_reason explain omitted results;
next_offset is null when no row fits. BigInts are decimal strings
and blobs are { "type": "blob", "base64": "..." }.
Example:
{
"query": "SELECT * FROM users WHERE age > ?",
"params": { "1": 21 },
"database": "customer_db"
}
execute_query
Executes a potentially destructive SQL query (INSERT, UPDATE, DELETE,
CREATE, etc.) against a database.
Parameters:
query (string, required): One write statement, maximum 10000
characters; includes mutating PRAGMAs and WITH-prefixed writes
params (object, optional): Same parameter types as the read tool
database (string, optional): Database name (uses context if not
provided)
Write result rows (such as RETURNING) are capped at 1000 rows and
the same byte budget. rowsAffected remains intact. Truncation does
not undo the write: do not rerun a write to fetch omitted rows.
describe_table
Gets schema information for a table.
Parameters:
table (string, required): Table name
database (string, optional): Database name (uses context if not
provided)
Example:
{
"table": "users",
"database": "customer_db"
}
vector_search
Performs vector similarity search using SQLite vector extensions.
Use Node.js 24.15.0 or newer and pnpm 12.5.1 (pinned in
package.json). .node-version selects the development runtime.
pnpm install
pnpm check
pnpm test
Vite+ provides the build, formatting, linting, type checking, and test
runner through vite.config.ts:
pnpm build — bundle the executable and declarations into dist/
pnpm start — run the built server with your Turso configuration
pnpm dev — rebuild on source changes
pnpm inspect — open the MCP inspector against the built server
pnpm check — check formatting, lint, and types
pnpm check:fix — apply formatting and safe lint fixes
pnpm format / pnpm format:check — format or check formatting
pnpm test — build and run offline SQL, permission, token, MCP
handler, and CLI tests; no Turso credentials or live database access
needed. SQL execution tests use an isolated in-memory libSQL
database.
Dependency versions live in the pnpm-workspace.yaml catalog. New
releases must be at least two days old before installation.
Editors
Install the Oxc extension in Zed or the Vite Plus Extension
Pack in VS Code. Checked-in .zed/settings.json and
.vscode/settings.json use Oxfmt with the shared vite.config.ts
formatting settings. Prettier configuration is no longer used.
Publishing
pnpm changeset
pnpm version
pnpm check
pnpm test
pnpm release
pnpm release builds and publishes through Changesets. pnpm pack
can verify the package locally without publishing.
Troubleshooting
API Token Issues
If you encounter authentication errors:
Verify your Turso API token is valid and has the necessary
permissions
Check that your organization name is correct
Ensure your token hasn't expired
Database Connection Issues
If you have trouble connecting to databases:
Verify the database exists in your organization
Check that your API token has access to the database
Ensure the database name is spelled correctly
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
🗂️ A Model Context Protocol (MCP) server that provides integration with Turso databases for LLMs. This server implements a two-level authentication system to handle both organization-level and databa
🗂️ A Model Context Protocol (MCP) server that provides integration with Turso databases for LLMs. This server implements a two-level authentication system to handle both organization-level and database-level operations, making it easy to manage and query Turso databases directly from LLMs.
上次檢查時間:2026-10-28。 🗂️ A Model Context Protocol (MCP) server that provides integration with Turso databases for LLMs. This server implements a two-level authentication system to handle both organization-level and database-level operations, making it easy to manage and query Turso databases directly from LLMs.