Skip to content

Commit 83d3947

Browse files
Souhar-dyaSouhar-dya
authored
Add MCP Database Server with multi-database support and natural language queries (github#284)
- Supports SQLite, PostgreSQL, and MySQL databases - Natural language to SQL query conversion - Direct SQL execution with safety checks - Schema inspection and table listing - FastAPI web interface with health checks - Comprehensive Docker deployment support
1 parent 3fd4921 commit 83d3947

3 files changed

Lines changed: 227 additions & 0 deletions

File tree

‎servers/database-server/readme.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# MCP Database Server
2+
3+
Comprehensive database server supporting PostgreSQL, MySQL, and SQLite with natural language SQL query capabilities. Enables AI agents to interact with databases through both direct SQL and natural language queries.
4+
5+
## Features
6+
7+
- **Multi-Database Support**: Works with SQLite, PostgreSQL, and MySQL
8+
- **Natural Language Queries**: Convert natural language to SQL automatically
9+
- **Direct SQL Execution**: Execute raw SQL with safety checks
10+
- **Schema Inspection**: List tables and describe table structures
11+
- **FastAPI Web Interface**: RESTful API endpoints for web integration
12+
- **Docker Ready**: Fully containerized with health checks
13+
14+
## Available MCP Tools
15+
16+
### `query_database`
17+
**Description**: Execute natural language queries against the database and convert them to SQL
18+
19+
**Usage**: Ask questions like "Show me all users created in the last week" or "Find the top 10 products by sales"
20+
21+
**Arguments**:
22+
- `query` (string): Natural language description of what you want to query from the database
23+
24+
### `list_tables`
25+
**Description**: List all available tables in the current database
26+
27+
**Usage**: Ask "What tables are available?" or "Show me the database structure"
28+
29+
### `describe_table`
30+
**Description**: Get detailed schema information for a specific table including columns, types, and constraints
31+
32+
**Usage**: Ask "Describe the users table" or "What columns does the products table have?"
33+
34+
**Arguments**:
35+
- `table_name` (string): Name of the table to describe
36+
37+
### `execute_sql`
38+
**Description**: Execute raw SQL queries with safety checks and validation
39+
40+
**Usage**: Execute specific SQL commands when you need precise control
41+
42+
**Arguments**:
43+
- `query` (string): SQL query to execute
44+
45+
### `connect_to_database`
46+
**Description**: Connect to a new database using provided connection details
47+
48+
**Usage**: Switch between different databases during your session
49+
50+
**Arguments**:
51+
- `connection_string` (string): Database connection string
52+
53+
### `get_connection_examples`
54+
**Description**: Get example connection strings for different database types (SQLite, PostgreSQL, MySQL)
55+
56+
**Usage**: Ask "How do I connect to a PostgreSQL database?" or "Show me connection examples"
57+
58+
### `get_current_database_info`
59+
**Description**: Get information about the currently connected database including type, version, and connection status
60+
61+
**Usage**: Ask "What database am I connected to?" or "Show me current connection details"
62+
63+
## Example Queries
64+
65+
Here are some example questions you can ask your agent:
66+
67+
```python
68+
# Basic queries
69+
"Show me all users in the database"
70+
"What tables are available?"
71+
"Describe the products table structure"
72+
73+
# Complex analysis
74+
"Find the top 5 customers by total order value"
75+
"Show me users who registered in the last month"
76+
"What's the average product price by category?"
77+
78+
# Data exploration
79+
"How many orders were placed yesterday?"
80+
"List all products that are out of stock"
81+
"Find duplicate email addresses in the users table"
82+
```
83+
84+
## Configuration
85+
86+
The server requires a `DATABASE_URL` environment variable with your database connection string:
87+
88+
### SQLite (recommended for testing)
89+
```
90+
DATABASE_URL=sqlite+aiosqlite:///data/mydb.db
91+
```
92+
93+
### PostgreSQL
94+
```
95+
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/mydb
96+
```
97+
98+
### MySQL
99+
```
100+
DATABASE_URL=mysql+aiomysql://user:password@localhost:3306/mydb
101+
```
102+
103+
## Docker Usage
104+
105+
```bash
106+
# Run with SQLite (simplest setup)
107+
docker run -d \
108+
-p 3000:3000 \
109+
-e DATABASE_URL=sqlite+aiosqlite:///data/mydb.db \
110+
souhardyak/mcp-db-server
111+
112+
# Run with PostgreSQL
113+
docker run -d \
114+
-p 3000:3000 \
115+
-e DATABASE_URL=postgresql+asyncpg://user:password@host:5432/db \
116+
souhardyak/mcp-db-server
117+
118+
# Run with persistent SQLite storage
119+
docker run -d \
120+
-p 3000:3000 \
121+
-v /host/data:/data \
122+
-e DATABASE_URL=sqlite+aiosqlite:///data/mydb.db \
123+
souhardyak/mcp-db-server
124+
```
125+
126+
## Health Check
127+
128+
The server provides a health endpoint at `/health` that returns database connectivity status.
129+
130+
## Source Code
131+
132+
Full source code and documentation available at: https://github.com/Souhar-dya/mcp-db-server

‎servers/database-server/server.yaml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: database-server
2+
image: souhardyak/mcp-db-server
3+
type: server
4+
meta:
5+
category: database
6+
tags:
7+
- database
8+
- sql
9+
- postgresql
10+
- mysql
11+
- sqlite
12+
- natural-language
13+
- ai-assistant
14+
about:
15+
title: MCP Database Server
16+
description: Comprehensive database server supporting PostgreSQL, MySQL, and SQLite with natural language SQL query capabilities. Enables AI agents to interact with databases through both direct SQL and natural language queries.
17+
icon: https://github.com/__avatars/u/182288589?s=200&v=4
18+
source:
19+
project: https://github.com/Souhar-dya/mcp-db-server
20+
config:
21+
description: Configure the database connection. Supports SQLite, PostgreSQL, and MySQL databases with comprehensive querying capabilities.
22+
env:
23+
- name: DATABASE_URL
24+
example: "sqlite+aiosqlite:///data/mydb.db"
25+
value: '{{database-server.database_url}}'
26+
parameters:
27+
type: object
28+
properties:
29+
database_url:
30+
type: string
31+
title: "Database Connection URL"
32+
description: "Connection string for your database. Examples: SQLite: sqlite+aiosqlite:///data/mydb.db, PostgreSQL: postgresql+asyncpg://user:password@localhost:5432/mydb, MySQL: mysql+aiomysql://user:password@localhost:3306/mydb"
33+
required:
34+
- database_url

‎servers/database-server/tools.json‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
[
2+
{
3+
"name": "query_database",
4+
"description": "Execute natural language queries against the database and convert them to SQL",
5+
"arguments": [
6+
{
7+
"name": "query",
8+
"type": "string",
9+
"desc": "Natural language description of what you want to query from the database"
10+
}
11+
]
12+
},
13+
{
14+
"name": "list_tables",
15+
"description": "List all available tables in the current database",
16+
"arguments": []
17+
},
18+
{
19+
"name": "describe_table",
20+
"description": "Get detailed schema information for a specific table including columns, types, and constraints",
21+
"arguments": [
22+
{
23+
"name": "table_name",
24+
"type": "string",
25+
"desc": "Name of the table to describe"
26+
}
27+
]
28+
},
29+
{
30+
"name": "execute_sql",
31+
"description": "Execute raw SQL queries with safety checks and validation",
32+
"arguments": [
33+
{
34+
"name": "query",
35+
"type": "string",
36+
"desc": "SQL query to execute"
37+
}
38+
]
39+
},
40+
{
41+
"name": "connect_to_database",
42+
"description": "Connect to a new database using provided connection details",
43+
"arguments": [
44+
{
45+
"name": "connection_string",
46+
"type": "string",
47+
"desc": "Database connection string (e.g., postgresql://user:pass@host:port/db)"
48+
}
49+
]
50+
},
51+
{
52+
"name": "get_connection_examples",
53+
"description": "Get example connection strings for different database types (SQLite, PostgreSQL, MySQL)",
54+
"arguments": []
55+
},
56+
{
57+
"name": "get_current_database_info",
58+
"description": "Get information about the currently connected database including type, version, and connection status",
59+
"arguments": []
60+
}
61+
]

0 commit comments

Comments
 (0)