tbls

Provides access to tbls-generated JSON schema data and supports safe SQL querying for MySQL and SQLite

typescript

GitHub Stars

typescript

Language

4 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "yhosok-tbls-mcp-server": {
      "command": "npx",
      "args": [
        "github:yhosok/tbls-mcp-server",
        "--schema-source",
        "/path/to/tbls/schema.json",
        "--database-url",
        "mysql://user:password@localhost:3306/database"
      ],
      "env": {
        "LOG_LEVEL": "info",
        "DATABASE_URL": "mysql://user:password@localhost:3306/database",
        "TBLS_SCHEMA_SOURCE": "/path/to/tbls/schema.json"
      }
    }
  }
}

You have a Model Context Protocol (MCP) server that exposes tbls-generated database schema information and can run safe SQL queries against MySQL or SQLite. It’s designed to be used from MCP clients to explore schemas, tables, and indexes, and to execute read-only queries against connected databases with strong validation and security features.

How to use

Start by running the MCP server using the provided CLI command. This server lets you explore tbls-derived schemas and, when you connect to a database, run safe SELECT queries.

Connect from an MCP client such as Claude Desktop by configuring an MCP server entry that points to the local or remote server. You can use the standard npx invocation to start the server and pass the required paths to your tbls JSON schema and, if available, a database URL.

Once running, you can request information like the complete list of schemas, table details, and index information. When a database connection is configured, you can execute safe SELECT queries with parameterization to retrieve data. Always use parameterized queries to prevent SQL injection and rely on the server’s protections (only SELECT statements are allowed, timeouts are enforced, and multi-statement attempts are blocked).

How to install

Prerequisites: Node.js 18 or higher, tbls installed and configured, and optional access to a MySQL or SQLite database for SQL query features.

Step-by-step commands you can run to get started:

# Ensure you have Node.js 18+ installed
node -v

# Install or use npx to run the MCP server directly
npx github:yhosok/tbls-mcp-server --schema-source /path/to/tbls/schema.json

# If you prefer to clone and run locally
git clone https://github.com/yhosok/tbls-mcp-server.git
cd tbls-mcp-server
npm install
npm run build

# Start the server with your schema
node dist/index.js --schema-source /path/to/tbls/schema.json

Configuration and usage notes

You can start with a minimal CLI usage and then switch to a configuration file for repeatable setups.

{
  "schemaSource": "/path/to/tbls/schema.json",
  "logLevel": "info",
  "database": {
    "type": "mysql",
    "connectionString": "mysql://username:password@localhost:3306/database_name"
  }
}

Where to put and how to reference JSON schema

The server consumes a tbls-generated JSON schema file or a directory containing such JSON files. Provide the path to the file or directory that contains the schema information.

Example usage with a single JSON schema file:

npx github:yhosok/tbls-mcp-server --schema-source /path/to/tbls/schema.json

SQL query tool capabilities

When a database is configured, you can execute SELECT queries through the MCP interface. The tool enforces safety features such as parameterized queries, query timeouts, and prevention of multi-statement injections.

{
  "query": "SELECT * FROM users WHERE active = ?",
  "parameters": [true],
  "timeout": 30000
}

Available tools

execute-sql

SQL Query Tool to run safe SELECT queries against connected MySQL or SQLite databases with parameterization, timeouts, and protections against injection.

Built by

VeilStrat

AI signals for GTM teams