Skip to main content
Glama

tbls MCP Server

by yhosok
GitHub
TypeScript
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

tbls MCP Server

⚠️ EXPERIMENTAL SOFTWARE This application is experimental software with insufficient testing coverage (~66% currently). It is not suitable for production use. We recommend experimental use only for development and testing purposes. If you plan to use it in production, please conduct thorough testing beforehand.

A Model Context Protocol (MCP) server that provides access to database schema information generated by tbls and enables SQL query execution on MySQL and SQLite databases.

Features

  • JSON Schema Support: Primary support for tbls-generated JSON schema files with optimal performance
  • JSON-Only Support: Uses JSON schema format from tbls for optimal performance
  • Multiple Resource Types: Access schemas, tables, and index information through MCP resources
  • SQL Query Execution: Execute SELECT queries on MySQL and SQLite databases with comprehensive security
  • Type Safety: Full TypeScript implementation with zod validation
  • Error Handling: Robust error handling using neverthrow Result types
  • MCP Compatible: Works with Claude Desktop and other MCP clients
  • Flexible Configuration: Support for both CLI arguments and configuration files

MCP Client Configuration

To use this server with MCP clients, add the following configuration to your MCP client's configuration file.

Example: Claude Desktop

Add to your Claude Desktop configuration file (claude_desktop_config.json):

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

Note: You can create a .tbls-mcp-server.json configuration file to specify server options (see Configuration section below) and use just the command without arguments in your MCP client configuration.

Installation

Prerequisites

  • Node.js 18 or higher
  • tbls installed and configured
  • Database access (MySQL or SQLite) - optional for SQL query features
npx github:yhosok/tbls-mcp-server --schema-source /path/to/tbls/schema.json

Clone and Run Locally

git clone https://github.com/yhosok/tbls-mcp-server.git cd tbls-mcp-server npm install npm run build # Run the server node dist/index.js --schema-source /path/to/tbls/schema.json

Usage

Basic Usage (Schema Information Only)

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

With Database Connection (Full Features)

npx github:yhosok/tbls-mcp-server \ --schema-source /path/to/tbls/schema.json \ --database-url mysql://user:pass@localhost:3306/mydb

Using Configuration File

npx github:yhosok/tbls-mcp-server --config .tbls-mcp-server.json

JSON Schema Sample

Example of a tbls-generated JSON schema file structure:

{ "name": "myapp", "type": "mysql", "tables": [ { "name": "users", "type": "table", "comment": "User accounts", "columns": [ { "name": "id", "type": "int(11)", "nullable": false, "primary": true, "comment": "Primary key" }, { "name": "email", "type": "varchar(255)", "nullable": false, "unique": true, "comment": "User email address" } ], "indexes": [ { "name": "PRIMARY", "columns": ["id"], "unique": true }, { "name": "idx_email", "columns": ["email"], "unique": true } ] } ] }

Examples

Setting up with tbls

First, install tbls by following the instructions at https://github.com/k1LoW/tbls.

Then generate schema documentation:

# Generate schema documentation (default output: ./dbdoc) tbls doc mysql://user:pass@localhost:3306/mydb # Or generate JSON schema directly tbls out -t json mysql://user:pass@localhost:3306/mydb -o ./custom/schema/path/schema.json # Start MCP server npx github:yhosok/tbls-mcp-server --schema-source ./dbdoc/schema.json

Directory Structure

Expected tbls output structure:

./dbdoc/ ├── schema.json # Complete schema information (required) └── README.md # Human-readable overview (optional)

Note:

  • Use tbls out -t json to generate the JSON schema file
  • The default output file is schema.json in the specified directory
  • The --schema-source option can point to either a JSON file or directory containing JSON files

Using with Claude Desktop

  1. Configure Claude Desktop:
    { "mcpServers": { "tbls": { "command": "npx", "args": [ "github:yhosok/tbls-mcp-server", "--schema-source", "/Users/username/projects/myapp/dbdoc/schema.json", "--database-url", "mysql://user:password@localhost:3306/myapp" ] } } }
  2. Restart Claude Desktop and the tbls server will be available
  3. Query your database schema:
    • "Show me all tables in the database"
    • "What columns does the users table have?"
    • "Show me the relationship between users and posts"
    • "Execute: SELECT COUNT(*) FROM users WHERE active = true"

Common SQL Queries

Schema exploration:

-- MySQL SHOW TABLES; SHOW COLUMNS FROM users; SELECT * FROM information_schema.table_constraints WHERE table_name = 'users'; -- SQLite SELECT name FROM sqlite_master WHERE type='table'; PRAGMA table_info(users);

Data analysis:

-- User statistics SELECT COUNT(*) as total_users, COUNT(CASE WHEN active = 1 THEN 1 END) as active_users, COUNT(CASE WHEN created_at > DATE_SUB(NOW(), INTERVAL 30 DAY) THEN 1 END) as recent_users FROM users; -- Popular posts SELECT p.title, p.created_at, COUNT(c.id) as comment_count FROM posts p LEFT JOIN comments c ON p.id = c.post_id GROUP BY p.id ORDER BY comment_count DESC LIMIT 10;

MCP Resources

The server exposes tbls-generated schema information through the following MCP resources:

URI PatternDescriptionDiscovery Required
schema://listComplete list of all available database schemas with metadata including schema names, table counts, and version information. URI format: schema://listNo
schema://{schemaName}/tablesComprehensive list of all tables within the {schemaName} schema, including table metadata, row counts, and basic structure information. URI format: schema://[schema_name]/tables (example: schema://default/tables, schema://public/tables)Yes
table://{schemaName}/{tableName}Complete detailed information about the {tableName} table including column definitions with data types, constraints, indexes, foreign key relationships, and table statistics. URI format: table://[schema_name]/[table_name] (example: table://default/users, table://public/orders)Yes
table://{schemaName}/{tableName}/indexesDetailed index information for the {tableName} table including index names, types (primary, unique, regular), column compositions, and performance statistics. URI format: table://[schema_name]/[table_name]/indexes (example: table://default/users/indexes, table://public/orders/indexes)Yes

MCP Tools

The server provides SQL query execution capabilities when a database connection is configured:

SQL Query Tool (execute-sql)

Purpose: Execute SELECT queries on connected MySQL or SQLite databases with comprehensive security features.

Security Features:

  • ✅ SELECT queries only - INSERT, UPDATE, DELETE, DROP, etc. are blocked
  • ✅ Parameterized queries prevent SQL injection attacks
  • ✅ Query timeout protection prevents long-running queries
  • ✅ Multiple statement prevention blocks compound SQL injection
  • ✅ Input sanitization removes dangerous patterns

Supported Databases:

  • MySQL (via connection string or individual parameters)
  • SQLite (file path or : database)

Parameters:

  • query (required): SQL SELECT query to execute
  • parameters (optional): Array of parameters for prepared statements
  • timeout (optional): Query timeout in milliseconds (1000-300000, default: 30000)

Usage Examples:

{ "query": "SELECT * FROM users WHERE active = ?", "parameters": [true] }
{ "query": "SELECT u.name, COUNT(p.id) as post_count FROM users u LEFT JOIN posts p ON u.id = p.user_id GROUP BY u.id", "parameters": [] }
{ "query": "SHOW TABLES", "parameters": [], "timeout": 10000 }

Response Format:

{ "rows": [ {"id": 1, "name": "John Doe", "email": "john@example.com"}, {"id": 2, "name": "Jane Smith", "email": "jane@example.com"} ], "rowCount": 2, "columns": [ {"name": "id", "type": "int"}, {"name": "name", "type": "varchar"}, {"name": "email", "type": "varchar"} ] }

Configuration

Command Line Arguments

  • --schema-source <path>: Path to tbls JSON schema file or directory (required)
  • --database-url <url>: Database connection string (optional)
  • --log-level <level>: Set logging level (debug, info, warn, error, default: info)
  • --config <path>: Path to configuration file
  • --help: Show help information
  • --version: Show version information

Environment Variables

  • TBLS_SCHEMA_SOURCE: Path to tbls JSON schema file or directory
  • DATABASE_URL: Database connection string (optional)
  • LOG_LEVEL: Logging level (debug, info, warn, error)

Configuration File

Create a .tbls-mcp-server.json file in your project root:

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

MySQL:

{ "database": { "type": "mysql", "connectionString": "mysql://user:password@host:port/database" } }

SQLite:

{ "database": { "type": "sqlite", "connectionString": "sqlite:///path/to/database.db" } }
Complete Configuration Examples

Production Setup with JSON Schema:

{ "schemaSource": "/opt/app/schema/production.json", "logLevel": "warn", "database": { "type": "mysql", "connectionString": "mysql://readonly_user:password@db.company.com:3306/production_db" } }

Development Setup with Local Files:

{ "schemaSource": "./dbdoc/schema.json", "logLevel": "debug", "database": { "type": "sqlite", "connectionString": "sqlite:///./dev.db" } }

Troubleshooting

Common Issues

Server fails to start:

  • Verify Node.js version (18+ required)
  • Check that the schema source file exists or directory contains tbls-generated files
  • For JSON: Ensure the JSON file is valid and contains proper schema structure
  • For directories: Ensure the directory contains proper .json files
  • Ensure database connection string is valid (if using database features)

No resources available:

  • Confirm tbls has generated JSON schema file in the specified location
  • Check file permissions on the schema file/directory
  • Enable debug logging: --log-level debug

Database connection issues:

  • Test database connectivity outside of the MCP server
  • Verify connection string format
  • Check firewall and network access
  • Ensure database user has appropriate permissions (SELECT at minimum)

SQL queries fail:

  • Only SELECT statements are allowed
  • Use parameterized queries with ? placeholders
  • Check query timeout settings
  • Review query syntax for your database type

Claude Desktop integration issues:

  • Restart Claude Desktop after configuration changes
  • Check configuration file syntax (valid JSON)
  • Verify file paths are absolute and accessible
  • Check Claude Desktop logs for error messages

Debug Mode

Enable debug logging to troubleshoot issues:

tbls-mcp-server --schema-source /path/to/schema.json --log-level debug

This will output detailed information about:

  • Configuration loading and schema source resolution
  • Resource discovery (JSON file vs directory detection)
  • Database connections
  • SQL query execution
  • Error details and diagnostics

Support

For issues and questions:

Development

Prerequisites

  • Node.js 18+
  • npm or yarn

Setup

git clone https://github.com/yhosok/tbls-mcp-server.git cd tbls-mcp-server npm install

Development Commands

# Start development server npm run dev # Run tests npm test # Run tests with coverage npm run test:coverage # Build for production npm run build # Run linter npm run lint

Testing

The project uses Jest for testing with a focus on Test-Driven Development (TDD):

# Run all tests npm test # Run tests in watch mode npm run test:watch # Generate coverage report npm run test:coverage

Architecture

The server is built using:

  • TypeScript: Type-safe implementation
  • @modelcontextprotocol/sdk: Official MCP SDK
  • neverthrow: Result types for error handling
  • zod: Schema validation
  • mysql2: MySQL database connectivity
  • sqlite3: SQLite database connectivity

Security

  • Only SELECT statements are permitted for SQL execution
  • Input validation using zod schemas
  • SQL injection prevention through parameterized queries
  • Connection string validation and sanitization

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Write tests for your changes
  4. Implement your changes
  5. Ensure all tests pass
  6. Submit a pull request

License

ISC License

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Provides access to database schema information generated by tbls and enables secure SQL query execution on MySQL and SQLite databases. Allows users to explore database structures, table relationships, and execute SELECT queries through natural language interactions.

  1. Features
    1. MCP Client Configuration
      1. Example: Claude Desktop
    2. Installation
      1. Prerequisites
      2. Via npx (Recommended for MCP)
      3. Clone and Run Locally
    3. Usage
      1. Basic Usage (Schema Information Only)
      2. With Database Connection (Full Features)
      3. Using Configuration File
    4. JSON Schema Sample
      1. Examples
        1. Setting up with tbls
        2. Directory Structure
        3. Using with Claude Desktop
        4. Common SQL Queries
      2. MCP Resources
        1. MCP Tools
          1. SQL Query Tool (execute-sql)
        2. Configuration
          1. Command Line Arguments
          2. Environment Variables
          3. Configuration File
        3. Troubleshooting
          1. Common Issues
          2. Debug Mode
          3. Support
        4. Development
          1. Prerequisites
          2. Setup
          3. Development Commands
          4. Testing
        5. Architecture
          1. Security
            1. Contributing
              1. License
                1. Related Projects

                  New MCP Servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/yhosok/tbls-mcp-server'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server