SqlSchemaBridgeMCP

yt3trees/SqlSchemaBridgeMCP

3.3

If you are the rightful owner of SqlSchemaBridgeMCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

SqlSchemaBridgeMCP is a Model-Context-Protocol (MCP) server that facilitates the translation of natural language queries into SQL by providing metadata about database schemas.

Tools
11
Resources
0
Prompts
0

SQL Schema Bridge MCP Server

dotnet nuget

Overview

graph TB
    User["👤 User"]
    Agent["🤖 AI Agent / MCP Client"]
    Server["🚀 SqlSchemaBridgeMCP Server"]
    Database[("💾 Live Database<br/>(SQL Server, MySQL, PostgreSQL, SQLite)")]
    CSVFiles["📄 CSV Files<br/>(tables.csv, columns.csv, relations.csv)"]

    subgraph "Available MCP Tools"
        QueryTools["🔍 Schema Querying"]
        EditTools["✏️ Schema Editing"]
        ConnectionTools["🔗 Database Connection"]
    end

    %% Main Flow
    User -->|"Ask question in natural language"| Agent
    Agent <-->|"MCP Protocol"| Server
    Server --> QueryTools
    Server --> EditTools
    Server --> ConnectionTools
    QueryTools <-->|"Read"| CSVFiles
    EditTools <-->|"Write"| CSVFiles
    ConnectionTools <-->|"Auto-import schema"| Database
    ConnectionTools -->|"Generate CSV files"| CSVFiles
    Agent -->|"Generate SQL based on schema"| User

SqlSchemaBridgeMCP is a Model-Context-Protocol (MCP) server designed to bridge the gap between natural language and SQL. It provides an AI agent with the necessary metadata about a database schema—such as table definitions, column details, and relationships—enabling the agent to accurately construct SQL queries based on user questions.

This server supports two approaches for managing schema information:

  • Manual Management: Read database schema information from local CSV files
  • Auto-Import: Connect directly to live databases (SQL Server, MySQL, PostgreSQL, SQLite) to automatically extract schema information

How It Works

When a user asks a question about data (e.g., "Show me the latest order date for each customer"), the AI agent interacts with this MCP server to understand the database structure:

sequenceDiagram
    participant User as 👤 User
    participant Agent as 🤖 AI Agent
    participant MCPServer as 🚀 MCP Server

    User->>Agent: "Show me the latest order date for each customer"

    Agent->>MCPServer: Inquire about schema (e.g., tables, columns, relations)
    note right of Agent: Uses tools like sql_schema_find_table, sql_schema_find_column, etc.

    MCPServer-->>Agent: Return schema metadata

    Agent->>User: Generate and return SQL query
  1. The agent calls tools like sql_schema_find_table and sql_schema_find_column to map logical names ("customer", "order date") to their physical counterparts in the database (Customers, OrderDate).
  2. The agent uses sql_schema_find_relations to discover how tables are connected (e.g., Customers.CustomerID -> Orders.CustomerID).
  3. Using the retrieved metadata, the agent assembles a precise SQL query to answer the user's question.

Features

  • Natural Language to SQL: Helps AI agents translate natural language questions into accurate SQL queries.
  • Local Metadata Management: Database schema information is managed through simple CSV files stored on your local machine.
  • Profile Support: Easily switch between different database schema definitions using profiles. This is ideal for managing multiple projects or environments (e.g., development, testing, production).

For Users: Getting Started

Follow these steps to configure and run the MCP server.

1. Installation

You have two options for installing the MCP server.

Option 1: Download from GitHub Releases
  1. Go to the GitHub Releases page for this project.
  2. Download the release package for your operating system (e.g., SqlSchemaBridgeMCP-win-x64.zip).
  3. Extract the downloaded zip file to a location of your choice.

[!NOTE]
This is the easiest method as it includes the .NET runtime and does not require any additional installations. Note that when a new version is released, you will need to download it manually to get the latest updates.

Option 2: Install from NuGet using dnx

This option is for users who have the .NET SDK installed and prefer to use the dnx command-line tool.

  1. Prerequisite: Install the .NET 10 SDK or a later version.

[!TIP] The dnx command will automatically fetch the SqlSchemaBridgeMCP package from NuGet the first time you run it, ensuring you are using the latest version available.

2. MCP Client Configuration

To use this MCP server with a client like the Gemini CLI, you need to configure the client to launch the server. Add or update the mcpServers configuration in your client's settings file (e.g., ~/.gemini/settings.json).

For Option 1 (GitHub Release)
{
  "mcpServers": {
    "SqlSchemaBridgeMCP": {
      "type": "stdio",
      "command": "C:\\path\\to\\your\\extracted\\folder\\SqlSchemaBridgeMCP.exe",
      "args": []
    }
  }
}
  • command: Replace this with the absolute path to the SqlSchemaBridgeMCP.exe you extracted.
  • For macOS or Linux, the command should be the path to the executable (e.g., ./SqlSchemaBridgeMCP).
For Option 2 (dnx)
{
  "mcpServers": {
    "SqlSchemaBridgeMCP": {
      "type": "stdio",
      "command": "dnx",
      "args": [
        "SqlSchemaBridgeMCP",
        "--yes"
      ]
    }
  }
}
  • The dnx command handles the download and execution of the server.

3. Metadata Configuration

The server loads schema information from CSV files located in profile directories. The server searches for these profiles in two locations:

  1. The path specified by the SQLSCHEMABRIDGEMCP_PROFILES_PATH environment variable (if set).
  2. The default folder named .SqlSchemaBridgeMCP inside your user's home directory (e.g., C:\Users\<UserName> on Windows or ~/ on macOS/Linux).

Directory Structure:

You can place profile folders (like ProjectA, Test) inside either of the locations mentioned above. The server will aggregate profiles from all search paths.

If a profile with the same name exists in multiple locations, the one in the path specified by the environment variable will take priority.

The .current_profile file, which stores the currently active profile, is always managed within the default ~/.SqlSchemaBridgeMCP directory.

Inside the profile root directories, create a subdirectory for each profile you want to use.

\.SqlSchemaBridgeMCP
|-- \ProjectA
|   |-- tables.csv
|   |-- columns.csv
|   |-- relations.csv
|-- \Test
|   |-- tables.csv
|   |-- columns.csv
|   |-- relations.csv
Example Profile: ProjectA

Create the files below in the C:\Users\<UserName>\.SqlSchemaBridgeMCP\ProjectA directory.

tables.csv

database_name,schema_name,logical_name,physical_name,primary_key,description
SalesDB,dbo,Customers,M_CUSTOMERS,CUSTOMER_ID,"Table to store basic customer information."
SalesDB,dbo,Order Headers,T_ORDER_HEADERS,ORDER_ID,"Stores order information from customers."
SalesDB,dbo,Products,M_PRODUCTS,PRODUCT_ID,"Master data for product information."
SalesDB,dbo,Order Details,T_ORDER_DETAILS,ORDER_DETAIL_ID,"Stores order detail information."

columns.csv

table_physical_name,logical_name,physical_name,data_type,description
M_CUSTOMERS,CustomerID,CUSTOMER_ID,int,"Primary key for the Customers table."
M_CUSTOMERS,CustomerName,CUSTOMER_NAME,"nvarchar(100)","Name of the customer."
M_CUSTOMERS,Address,ADDRESS,"nvarchar(255)",
T_ORDER_HEADERS,OrderID,ORDER_ID,int,"Primary key for the Order Headers table."
T_ORDER_HEADERS,CustomerID,CUSTOMER_ID,int,"Foreign key to the Customers table."
T_ORDER_HEADERS,OrderDate,ORDER_DATE,datetime,
T_ORDER_HEADERS,TotalAmount,TOTAL_AMOUNT,decimal,
M_PRODUCTS,ProductID,PRODUCT_ID,int,
M_PRODUCTS,ProductName,PRODUCT_NAME,"nvarchar(100)",
M_PRODUCTS,UnitPrice,UNIT_PRICE,decimal,
T_ORDER_DETAILS,OrderDetailID,ORDER_DETAIL_ID,int,
T_ORDER_DETAILS,OrderID,ORDER_ID,int,
T_ORDER_DETAILS,ProductID,PRODUCT_ID,int,
T_ORDER_DETAILS,Quantity,QUANTITY,int,

relations.csv

source_table,source_column,target_table,target_column
M_CUSTOMERS,CUSTOMER_ID,T_ORDER_HEADERS,CUSTOMER_ID
T_ORDER_HEADERS,ORDER_ID,T_ORDER_DETAILS,ORDER_ID
M_PRODUCTS,PRODUCT_ID,T_ORDER_DETAILS,PRODUCT_ID

Key Configuration Points:

  • No Profile Configuration Required: The server automatically uses the default profile on first startup and allows dynamic switching using the switch_profile tool.

4. Profile Management

Initial Startup
  • The server automatically uses the default profile on first startup
  • If the profile doesn't exist, you can still list available profiles using the list_available_profiles tool
Profile Switching

AI or users can manage profiles using the following tools:

  • sql_schema_switch_profile(profile_name): Switch to the specified profile
  • sql_schema_get_current_profile(): Get information about the currently active profile
  • sql_schema_list_available_profiles(): List all available profiles
Persistence
  • Profile switches are saved to a settings file (.current_profile)
  • The same profile will automatically be used on the next startup

For Developers: Local Development

Local Development Setup

To test this MCP server from the source code, you can configure your IDE to run the project directly using dotnet run. This is recommended for development purposes.

{
  "mcpServers": {
    "SqlSchemaBridgeMCP": {
      "type": "stdio",
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:\\work\\SqlSchemaBridgeMCP"
      ]
    }
  }
}

Development Profile Management:

  • Use the switch_profile tool to switch profiles during development
  • Settings file persistence ensures profiles are maintained across development sessions

Creating a Release Build (Self-Contained)

For distribution, you can publish the server as a self-contained application. This bundles the .NET runtime with your application, so it can run on machines without the .NET runtime installed.

Run the dotnet publish command, specifying the target runtime identifier (RID).

# For Windows x64
dotnet publish -c Release -r win-x64 --self-contained true

# For Linux x64
dotnet publish -c Release -r linux-x64 --self-contained true

# For macOS x64
dotnet publish -c Release -r osx-x64 --self-contained true

The output will be placed in the bin/Release/net8.0/<RID>/publish/ directory.