db-connect-mcp 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of db-connect-mcp might be problematic. Click here for more details.
- db_connect_mcp/__init__.py +30 -0
- db_connect_mcp/__main__.py +13 -0
- db_connect_mcp/adapters/__init__.py +72 -0
- db_connect_mcp/adapters/base.py +152 -0
- db_connect_mcp/adapters/clickhouse.py +298 -0
- db_connect_mcp/adapters/mysql.py +288 -0
- db_connect_mcp/adapters/postgresql.py +351 -0
- db_connect_mcp/core/__init__.py +13 -0
- db_connect_mcp/core/analyzer.py +114 -0
- db_connect_mcp/core/connection.py +371 -0
- db_connect_mcp/core/executor.py +239 -0
- db_connect_mcp/core/inspector.py +345 -0
- db_connect_mcp/models/__init__.py +23 -0
- db_connect_mcp/models/capabilities.py +98 -0
- db_connect_mcp/models/config.py +401 -0
- db_connect_mcp/models/database.py +112 -0
- db_connect_mcp/models/query.py +119 -0
- db_connect_mcp/models/statistics.py +176 -0
- db_connect_mcp/models/table.py +230 -0
- db_connect_mcp/server.py +496 -0
- db_connect_mcp-0.1.0.dist-info/METADATA +565 -0
- db_connect_mcp-0.1.0.dist-info/RECORD +25 -0
- db_connect_mcp-0.1.0.dist-info/WHEEL +4 -0
- db_connect_mcp-0.1.0.dist-info/entry_points.txt +2 -0
- db_connect_mcp-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,565 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: db-connect-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Multi-database MCP server for PostgreSQL, MySQL, and ClickHouse
|
|
5
|
+
Project-URL: Homepage, https://github.com/yugui923/db-connect-mcp
|
|
6
|
+
Project-URL: Repository, https://github.com/yugui923/db-connect-mcp
|
|
7
|
+
Project-URL: Issues, https://github.com/yugui923/db-connect-mcp/issues
|
|
8
|
+
Author-email: Yuri Gui <yugui923@users.noreply.github.com>
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: analysis,claude,clickhouse,data-exploration,database,mcp,mysql,postgresql
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Framework :: AsyncIO
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Database
|
|
19
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
20
|
+
Requires-Python: >=3.13
|
|
21
|
+
Requires-Dist: aiomysql>=0.2.0
|
|
22
|
+
Requires-Dist: asyncpg>=0.29.0
|
|
23
|
+
Requires-Dist: clickhouse-connect>=0.7.0
|
|
24
|
+
Requires-Dist: mcp>=1.0.0
|
|
25
|
+
Requires-Dist: pydantic>=2.0.0
|
|
26
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
27
|
+
Requires-Dist: sqlalchemy[asyncio]>=2.0.0
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# db-connect-mcp - Multi-Database MCP Server
|
|
31
|
+
|
|
32
|
+
A read-only MCP (Model Context Protocol) server for exploratory data analysis across multiple database systems. This server provides safe, read-only access to PostgreSQL, MySQL, and ClickHouse databases with comprehensive analysis capabilities.
|
|
33
|
+
|
|
34
|
+
## Quick Start
|
|
35
|
+
|
|
36
|
+
1. **Install:**
|
|
37
|
+
```bash
|
|
38
|
+
# Option 1: From PyPI (recommended)
|
|
39
|
+
pip install db-connect-mcp
|
|
40
|
+
|
|
41
|
+
# Option 2: From source
|
|
42
|
+
git clone https://github.com/yugui923/db-connect-mcp.git
|
|
43
|
+
cd db-connect-mcp
|
|
44
|
+
uv sync
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
2. **Configure** `.env`:
|
|
48
|
+
```env
|
|
49
|
+
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
|
|
50
|
+
# Also supports: postgresql://, pg://, jdbc:postgresql://
|
|
51
|
+
# MariaDB: mariadb://, jdbc:mysql://, jdbc:mariadb://
|
|
52
|
+
# ClickHouse: ch://, jdbc:clickhouse://
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
3. **Add to Claude Desktop** `claude_desktop_config.json`:
|
|
56
|
+
```json
|
|
57
|
+
{
|
|
58
|
+
"mcpServers": {
|
|
59
|
+
"db-connect": {
|
|
60
|
+
"command": "uv",
|
|
61
|
+
"args": ["run", "python", "C:/path/to/db-connect-mcp/main.py"],
|
|
62
|
+
"env": {
|
|
63
|
+
"DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
4. **Restart Claude Desktop** and start querying your database!
|
|
71
|
+
|
|
72
|
+
## Features
|
|
73
|
+
|
|
74
|
+
### 🗄️ Multi-Database Support
|
|
75
|
+
- **PostgreSQL** - Full support with advanced metadata and statistics
|
|
76
|
+
- **MySQL** - Complete support for MySQL and MariaDB databases
|
|
77
|
+
- **ClickHouse** - Support for analytical workloads and columnar storage
|
|
78
|
+
|
|
79
|
+
### 🔍 Database Exploration
|
|
80
|
+
- **List schemas** - View all schemas in the database
|
|
81
|
+
- **List tables** - See all tables with metadata (size, row counts, comments)
|
|
82
|
+
- **Describe tables** - Get detailed column information, indexes, and constraints
|
|
83
|
+
- **View relationships** - Understand foreign key relationships between tables
|
|
84
|
+
|
|
85
|
+
### 📊 Data Analysis
|
|
86
|
+
- **Column profiling** - Statistical analysis of column data
|
|
87
|
+
- Basic statistics (count, unique values, nulls)
|
|
88
|
+
- Numeric statistics (mean, median, std dev, quartiles)
|
|
89
|
+
- Value frequency distribution
|
|
90
|
+
- Cardinality analysis
|
|
91
|
+
- **Data sampling** - Preview table data with configurable limits
|
|
92
|
+
- **Custom queries** - Execute read-only SQL queries safely
|
|
93
|
+
- **Database profiling** - Get high-level database metrics and largest tables
|
|
94
|
+
|
|
95
|
+
### 🔒 Safety Features
|
|
96
|
+
- **Read-only enforcement** - All connections are read-only at multiple levels
|
|
97
|
+
- **Query validation** - Only SELECT and WITH queries are allowed
|
|
98
|
+
- **Automatic limits** - Queries are automatically limited to prevent large result sets
|
|
99
|
+
- **Connection string safety** - Automatically adds read-only parameters
|
|
100
|
+
- **Database-specific safety** - Each adapter implements appropriate safety measures
|
|
101
|
+
|
|
102
|
+
## Installation
|
|
103
|
+
|
|
104
|
+
### Prerequisites
|
|
105
|
+
- Python 3.13 or higher
|
|
106
|
+
- One or more of:
|
|
107
|
+
- PostgreSQL database (9.6+)
|
|
108
|
+
- MySQL/MariaDB database (5.7+/10.2+)
|
|
109
|
+
- ClickHouse database
|
|
110
|
+
|
|
111
|
+
### Method 1: Install from PyPI (Recommended)
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
pip install db-connect-mcp
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Method 2: Install from Source
|
|
118
|
+
|
|
119
|
+
For development or the latest features:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
# Clone the repository
|
|
123
|
+
git clone https://github.com/yugui923/db-connect-mcp.git
|
|
124
|
+
cd db-connect-mcp
|
|
125
|
+
|
|
126
|
+
# Install with uv (recommended)
|
|
127
|
+
uv sync
|
|
128
|
+
|
|
129
|
+
# Or install with pip
|
|
130
|
+
pip install -e .
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Method 3: Install from GitHub
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
pip install git+https://github.com/yugui923/db-connect-mcp.git
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Configuration
|
|
140
|
+
|
|
141
|
+
After installation, configure your database connection:
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
cp .env.example .env
|
|
145
|
+
# Edit .env with your database connection string
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Configuration
|
|
149
|
+
|
|
150
|
+
Create a `.env` file with your database connection string:
|
|
151
|
+
|
|
152
|
+
```env
|
|
153
|
+
DATABASE_URL=your_database_connection_string_here
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
The server automatically detects the database type and adds appropriate read-only parameters.
|
|
157
|
+
|
|
158
|
+
### Connection String Examples
|
|
159
|
+
|
|
160
|
+
The server now provides more flexible and secure URL handling:
|
|
161
|
+
- **Automatic driver detection**: Async drivers are automatically added if not specified
|
|
162
|
+
- **JDBC URL support**: JDBC prefixes are automatically handled
|
|
163
|
+
- `jdbc:postgresql://...` → `postgresql+asyncpg://...`
|
|
164
|
+
- `jdbc:mysql://...` → `mysql+aiomysql://...`
|
|
165
|
+
- Works with all dialect variations (e.g., `jdbc:postgres://`, `jdbc:mariadb://`)
|
|
166
|
+
- **Database dialect variations**: Common variations are automatically normalized
|
|
167
|
+
- PostgreSQL: `postgresql`, `postgres`, `pg`, `psql`, `pgsql`
|
|
168
|
+
- MySQL/MariaDB: `mysql`, `mariadb`, `maria`
|
|
169
|
+
- ClickHouse: `clickhouse`, `ch`, `click`
|
|
170
|
+
- **Allowlist-based parameter filtering**: Only known-safe parameters are preserved
|
|
171
|
+
- **Database-specific parameters**: Each database type has its own set of supported parameters
|
|
172
|
+
- **Robust parsing**: Handles various URL formats gracefully
|
|
173
|
+
|
|
174
|
+
**PostgreSQL:**
|
|
175
|
+
```
|
|
176
|
+
# Simple URL (driver automatically added)
|
|
177
|
+
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
|
|
178
|
+
|
|
179
|
+
# Common variations (all normalized to postgresql+asyncpg)
|
|
180
|
+
DATABASE_URL=postgres://user:pass@host:5432/db # Heroku, AWS RDS style
|
|
181
|
+
DATABASE_URL=pg://user:pass@host:5432/db # Short form
|
|
182
|
+
DATABASE_URL=psql://user:pass@host:5432/db # CLI style
|
|
183
|
+
|
|
184
|
+
# JDBC URLs (automatically converted)
|
|
185
|
+
DATABASE_URL=jdbc:postgresql://user:pass@host:5432/db # From Java apps
|
|
186
|
+
DATABASE_URL=jdbc:postgres://user:pass@host:5432/db # JDBC with variant
|
|
187
|
+
|
|
188
|
+
# With explicit async driver
|
|
189
|
+
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/db
|
|
190
|
+
|
|
191
|
+
# With supported parameters (see list below)
|
|
192
|
+
DATABASE_URL=postgres://user:pass@host:5432/db?application_name=myapp&connect_timeout=10
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
**Supported PostgreSQL Parameters:**
|
|
196
|
+
- `application_name` - Identifies your app in pg_stat_activity (useful for monitoring)
|
|
197
|
+
- `connect_timeout` - Connection timeout in seconds
|
|
198
|
+
- `command_timeout` - Default timeout for operations
|
|
199
|
+
- `ssl` / `sslmode` - SSL connection requirements (automatically converted for asyncpg compatibility)
|
|
200
|
+
- `server_settings` - Server settings dictionary
|
|
201
|
+
- `options` - Command-line options to send to server
|
|
202
|
+
- Performance tuning: `prepared_statement_cache_size`, `max_cached_statement_lifetime`, etc.
|
|
203
|
+
|
|
204
|
+
**MySQL/MariaDB:**
|
|
205
|
+
```
|
|
206
|
+
# Simple URL (driver automatically added)
|
|
207
|
+
DATABASE_URL=mysql://root:password@localhost:3306/mydb
|
|
208
|
+
|
|
209
|
+
# MariaDB URLs (normalized to mysql+aiomysql)
|
|
210
|
+
DATABASE_URL=mariadb://user:pass@host:3306/db # MariaDB style
|
|
211
|
+
DATABASE_URL=maria://user:pass@host:3306/db # Short form
|
|
212
|
+
|
|
213
|
+
# JDBC URLs (automatically converted)
|
|
214
|
+
DATABASE_URL=jdbc:mysql://user:pass@host:3306/db # From Java apps
|
|
215
|
+
DATABASE_URL=jdbc:mariadb://user:pass@host:3306/db # JDBC MariaDB
|
|
216
|
+
|
|
217
|
+
# With explicit async driver
|
|
218
|
+
DATABASE_URL=mysql+aiomysql://user:pass@host:3306/db
|
|
219
|
+
|
|
220
|
+
# With charset (critical for proper Unicode support)
|
|
221
|
+
DATABASE_URL=mariadb://user:pass@remote.host:3306/db?charset=utf8mb4
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
**Supported MySQL Parameters:**
|
|
225
|
+
- `charset` - Character encoding (e.g., utf8mb4) - **critical for data integrity**
|
|
226
|
+
- `use_unicode` - Enable Unicode support
|
|
227
|
+
- `connect_timeout`, `read_timeout`, `write_timeout` - Various timeouts
|
|
228
|
+
- `autocommit` - Transaction autocommit mode
|
|
229
|
+
- `init_command` - Initial SQL command to run
|
|
230
|
+
- `sql_mode` - SQL mode settings
|
|
231
|
+
- `time_zone` - Time zone setting
|
|
232
|
+
|
|
233
|
+
**ClickHouse:**
|
|
234
|
+
```
|
|
235
|
+
# Simple URL (driver automatically added)
|
|
236
|
+
DATABASE_URL=clickhouse://default:@localhost:9000/default
|
|
237
|
+
|
|
238
|
+
# Short forms (normalized to clickhouse+asynch)
|
|
239
|
+
DATABASE_URL=ch://user:pass@host:9000/db # Short form
|
|
240
|
+
DATABASE_URL=click://user:pass@host:9000/db # Alternative
|
|
241
|
+
|
|
242
|
+
# JDBC URLs (automatically converted)
|
|
243
|
+
DATABASE_URL=jdbc:clickhouse://user:pass@host:9000/db # From Java apps
|
|
244
|
+
DATABASE_URL=jdbc:ch://user:pass@host:9000/db # JDBC with short form
|
|
245
|
+
|
|
246
|
+
# With explicit async driver
|
|
247
|
+
DATABASE_URL=clickhouse+asynch://user:pass@host:9000/db
|
|
248
|
+
|
|
249
|
+
# With performance settings
|
|
250
|
+
DATABASE_URL=ch://user:pass@host:9000/db?timeout=60&max_threads=4
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
**Supported ClickHouse Parameters:**
|
|
254
|
+
- `database` - Default database selection
|
|
255
|
+
- `timeout`, `connect_timeout`, `send_receive_timeout` - Various timeouts
|
|
256
|
+
- `compress`, `compression` - Enable compression
|
|
257
|
+
- `max_block_size`, `max_threads` - Performance tuning
|
|
258
|
+
|
|
259
|
+
**Note:**
|
|
260
|
+
- SSL parameters (`ssl`, `sslmode`) are automatically converted to the correct format for asyncpg
|
|
261
|
+
- Certificate file parameters (`sslcert`, `sslkey`, `sslrootcert`) are filtered out as they can cause compatibility issues
|
|
262
|
+
- Only parameters known to work with async drivers are preserved
|
|
263
|
+
|
|
264
|
+
## Usage
|
|
265
|
+
|
|
266
|
+
### Running the Server
|
|
267
|
+
|
|
268
|
+
If installed from PyPI:
|
|
269
|
+
```bash
|
|
270
|
+
db-connect-mcp
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
If running from source:
|
|
274
|
+
```bash
|
|
275
|
+
python main.py
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
Or with uv:
|
|
279
|
+
```bash
|
|
280
|
+
uv run python main.py
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
### Using with Claude Desktop
|
|
284
|
+
|
|
285
|
+
Add the server to your Claude Desktop configuration (`claude_desktop_config.json`):
|
|
286
|
+
|
|
287
|
+
#### If installed from PyPI:
|
|
288
|
+
|
|
289
|
+
```json
|
|
290
|
+
{
|
|
291
|
+
"mcpServers": {
|
|
292
|
+
"db-connect": {
|
|
293
|
+
"command": "db-connect-mcp",
|
|
294
|
+
"env": {
|
|
295
|
+
"DATABASE_URL": "postgresql+asyncpg://user:pass@host:5432/db"
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
#### If installed from source:
|
|
303
|
+
|
|
304
|
+
```json
|
|
305
|
+
{
|
|
306
|
+
"mcpServers": {
|
|
307
|
+
"db-connect": {
|
|
308
|
+
"command": "python",
|
|
309
|
+
"args": ["C:/path/to/db-connect-mcp/main.py"],
|
|
310
|
+
"env": {
|
|
311
|
+
"DATABASE_URL": "postgresql+asyncpg://user:pass@host:5432/db"
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
#### Or using uv (for source installation):
|
|
319
|
+
|
|
320
|
+
```json
|
|
321
|
+
{
|
|
322
|
+
"mcpServers": {
|
|
323
|
+
"db-connect": {
|
|
324
|
+
"command": "uv",
|
|
325
|
+
"args": ["run", "python", "C:/path/to/db-connect-mcp/main.py"],
|
|
326
|
+
"env": {
|
|
327
|
+
"DATABASE_URL": "mysql+aiomysql://user:pass@host:3306/db"
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
}
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
You can configure multiple database connections:
|
|
335
|
+
```json
|
|
336
|
+
{
|
|
337
|
+
"mcpServers": {
|
|
338
|
+
"postgres-prod": {
|
|
339
|
+
"command": "uv",
|
|
340
|
+
"args": ["run", "python", "C:/path/to/db-connect-mcp/main.py"],
|
|
341
|
+
"env": {
|
|
342
|
+
"DATABASE_URL": "postgresql+asyncpg://user:pass@pg-host:5432/db"
|
|
343
|
+
}
|
|
344
|
+
},
|
|
345
|
+
"mysql-analytics": {
|
|
346
|
+
"command": "uv",
|
|
347
|
+
"args": ["run", "python", "C:/path/to/db-connect-mcp/main.py"],
|
|
348
|
+
"env": {
|
|
349
|
+
"DATABASE_URL": "mysql+aiomysql://user:pass@mysql-host:3306/analytics"
|
|
350
|
+
}
|
|
351
|
+
}
|
|
352
|
+
}
|
|
353
|
+
}
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
## Database Feature Support
|
|
357
|
+
|
|
358
|
+
| Feature | PostgreSQL | MySQL | ClickHouse |
|
|
359
|
+
|---------|------------|-------|------------|
|
|
360
|
+
| Schemas | ✅ Full | ✅ Full | ✅ Full |
|
|
361
|
+
| Tables | ✅ Full | ✅ Full | ✅ Full |
|
|
362
|
+
| Views | ✅ Full | ✅ Full | ✅ Full |
|
|
363
|
+
| Indexes | ✅ Full | ✅ Full | ⚠️ Limited |
|
|
364
|
+
| Foreign Keys | ✅ Full | ✅ Full | ❌ No |
|
|
365
|
+
| Constraints | ✅ Full | ✅ Full | ⚠️ Limited |
|
|
366
|
+
| Table Size | ✅ Exact | ✅ Exact | ✅ Exact |
|
|
367
|
+
| Row Count | ✅ Exact | ✅ Exact | ✅ Exact |
|
|
368
|
+
| Column Stats | ✅ Full | ✅ Full | ✅ Full |
|
|
369
|
+
| Sampling | ✅ Full | ✅ Full | ✅ Full |
|
|
370
|
+
|
|
371
|
+
## Available Tools
|
|
372
|
+
|
|
373
|
+
### list_schemas
|
|
374
|
+
List all schemas in the database.
|
|
375
|
+
|
|
376
|
+
### list_tables
|
|
377
|
+
List all tables in a schema with metadata.
|
|
378
|
+
- Parameters:
|
|
379
|
+
- `schema` (optional): Schema name (default: "public")
|
|
380
|
+
|
|
381
|
+
### describe_table
|
|
382
|
+
Get detailed information about a table.
|
|
383
|
+
- Parameters:
|
|
384
|
+
- `table_name`: Name of the table
|
|
385
|
+
- `schema` (optional): Schema name (default: "public")
|
|
386
|
+
|
|
387
|
+
### analyze_column
|
|
388
|
+
Analyze a column with statistics and distribution.
|
|
389
|
+
- Parameters:
|
|
390
|
+
- `table_name`: Name of the table
|
|
391
|
+
- `column_name`: Name of the column
|
|
392
|
+
- `schema` (optional): Schema name (default: "public")
|
|
393
|
+
|
|
394
|
+
### sample_data
|
|
395
|
+
Get a sample of data from a table.
|
|
396
|
+
- Parameters:
|
|
397
|
+
- `table_name`: Name of the table
|
|
398
|
+
- `schema` (optional): Schema name (default: "public")
|
|
399
|
+
- `limit` (optional): Number of rows (default: 100, max: 1000)
|
|
400
|
+
|
|
401
|
+
### execute_query
|
|
402
|
+
Execute a read-only SQL query.
|
|
403
|
+
- Parameters:
|
|
404
|
+
- `query`: SQL query (must be SELECT or WITH)
|
|
405
|
+
- `limit` (optional): Maximum rows (default: 1000, max: 10000)
|
|
406
|
+
|
|
407
|
+
### get_table_relationships
|
|
408
|
+
Get foreign key relationships in a schema.
|
|
409
|
+
- Parameters:
|
|
410
|
+
- `schema` (optional): Schema name (default: "public")
|
|
411
|
+
|
|
412
|
+
### profile_database
|
|
413
|
+
Get a high-level profile of the entire database.
|
|
414
|
+
|
|
415
|
+
## Example Usage in Claude
|
|
416
|
+
|
|
417
|
+
Once configured, you can use the server in Claude:
|
|
418
|
+
|
|
419
|
+
```
|
|
420
|
+
"Can you analyze my database and tell me about the table structure?"
|
|
421
|
+
|
|
422
|
+
"Show me the relationships between tables in the public schema"
|
|
423
|
+
|
|
424
|
+
"What's the distribution of values in the users.created_at column?"
|
|
425
|
+
|
|
426
|
+
"Give me a sample of data from the orders table"
|
|
427
|
+
|
|
428
|
+
"Run this query: SELECT COUNT(*) FROM users WHERE created_at > '2024-01-01'"
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
### Database-Specific Examples
|
|
432
|
+
|
|
433
|
+
**Working with PostgreSQL:**
|
|
434
|
+
```
|
|
435
|
+
"List all schemas except system ones"
|
|
436
|
+
"Show me the foreign key relationships in the sales schema"
|
|
437
|
+
"Analyze the performance of indexes on the products table"
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
**Working with MySQL:**
|
|
441
|
+
```
|
|
442
|
+
"What storage engines are being used in my database?"
|
|
443
|
+
"Show me all tables in the information_schema"
|
|
444
|
+
"Analyze the customer_orders table structure"
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
**Working with ClickHouse:**
|
|
448
|
+
```
|
|
449
|
+
"Show me the partitions for the events table"
|
|
450
|
+
"What's the compression ratio for the analytics.clicks table?"
|
|
451
|
+
"Sample 1000 rows from the metrics table"
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
## Safety and Security
|
|
455
|
+
|
|
456
|
+
- **Read-only by design**: The server enforces read-only access at multiple levels:
|
|
457
|
+
- Connection string parameters
|
|
458
|
+
- Session-level settings
|
|
459
|
+
- Query validation
|
|
460
|
+
|
|
461
|
+
- **No data modification**: INSERT, UPDATE, DELETE, CREATE, DROP, and other modification statements are blocked
|
|
462
|
+
|
|
463
|
+
- **Query limits**: All queries are automatically limited to prevent excessive resource usage
|
|
464
|
+
|
|
465
|
+
- **No sensitive operations**: No access to system catalogs or administrative functions
|
|
466
|
+
|
|
467
|
+
## Development
|
|
468
|
+
|
|
469
|
+
### Project Structure
|
|
470
|
+
```
|
|
471
|
+
db-connect-mcp/
|
|
472
|
+
├── src/
|
|
473
|
+
│ ├── adapters/ # Database-specific adapters
|
|
474
|
+
│ │ ├── __init__.py
|
|
475
|
+
│ │ ├── base.py # Base adapter interface
|
|
476
|
+
│ │ ├── postgresql.py # PostgreSQL adapter
|
|
477
|
+
│ │ ├── mysql.py # MySQL adapter
|
|
478
|
+
│ │ └── clickhouse.py # ClickHouse adapter
|
|
479
|
+
│ ├── core/ # Core functionality
|
|
480
|
+
│ │ ├── __init__.py
|
|
481
|
+
│ │ ├── connection.py # Database connection management
|
|
482
|
+
│ │ ├── executor.py # Query execution
|
|
483
|
+
│ │ ├── inspector.py # Metadata inspection
|
|
484
|
+
│ │ └── analyzer.py # Statistical analysis
|
|
485
|
+
│ ├── models/ # Data models
|
|
486
|
+
│ │ ├── __init__.py
|
|
487
|
+
│ │ ├── capabilities.py # Database capabilities
|
|
488
|
+
│ │ ├── config.py # Configuration models
|
|
489
|
+
│ │ ├── database.py # Database models
|
|
490
|
+
│ │ ├── query.py # Query models
|
|
491
|
+
│ │ ├── statistics.py # Statistics models
|
|
492
|
+
│ │ └── table.py # Table metadata models
|
|
493
|
+
│ ├── __init__.py
|
|
494
|
+
│ ├── __main__.py
|
|
495
|
+
│ └── server.py # Main MCP server implementation
|
|
496
|
+
├── tests/
|
|
497
|
+
│ ├── conftest.py # Test configuration
|
|
498
|
+
│ └── test_server.py # Integration tests
|
|
499
|
+
├── .env.example # Example environment configuration
|
|
500
|
+
├── main.py # Entry point
|
|
501
|
+
├── pyproject.toml # Project dependencies
|
|
502
|
+
└── README.md # This file
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
### Architecture
|
|
506
|
+
|
|
507
|
+
The server uses an adapter pattern to support multiple database systems:
|
|
508
|
+
|
|
509
|
+
- **Adapters**: Each database type has its own adapter that implements database-specific functionality
|
|
510
|
+
- **Core**: Shared functionality for connection management, query execution, and metadata inspection
|
|
511
|
+
- **Models**: Pydantic models for type safety and validation
|
|
512
|
+
- **Server**: MCP server implementation that routes requests to appropriate components
|
|
513
|
+
|
|
514
|
+
### Running Tests
|
|
515
|
+
```bash
|
|
516
|
+
# Run integration tests
|
|
517
|
+
uv run python tests/test_server.py
|
|
518
|
+
|
|
519
|
+
# Or with pytest (when available)
|
|
520
|
+
uv run pytest tests/
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
## Troubleshooting
|
|
524
|
+
|
|
525
|
+
### Connection Issues
|
|
526
|
+
- Verify your DATABASE_URL is correct and includes the appropriate driver
|
|
527
|
+
- Check network connectivity to the database
|
|
528
|
+
- Ensure the database user has appropriate read permissions
|
|
529
|
+
- For PostgreSQL: Check if SSL is required (`?ssl=require`)
|
|
530
|
+
- For MySQL: Verify charset settings (`?charset=utf8mb4`)
|
|
531
|
+
- For ClickHouse: Check port (default is 9000 for native, 8123 for HTTP)
|
|
532
|
+
|
|
533
|
+
### Database-Specific Issues
|
|
534
|
+
|
|
535
|
+
**PostgreSQL:**
|
|
536
|
+
- Ensure `asyncpg` driver is specified for async operations
|
|
537
|
+
- SSL certificates may be required for cloud databases
|
|
538
|
+
|
|
539
|
+
**MySQL/MariaDB:**
|
|
540
|
+
- Use `aiomysql` driver for async support
|
|
541
|
+
- Check MySQL version compatibility (5.7+ or MariaDB 10.2+)
|
|
542
|
+
- Verify charset and collation settings
|
|
543
|
+
|
|
544
|
+
**ClickHouse:**
|
|
545
|
+
- Use `asynch` driver for async operations
|
|
546
|
+
- Note that ClickHouse has limited support for foreign keys and constraints
|
|
547
|
+
- Some statistical functions may not be available
|
|
548
|
+
|
|
549
|
+
### Permission Errors
|
|
550
|
+
- The database user needs at least SELECT permissions on the schemas/tables you want to analyze
|
|
551
|
+
- Some statistical functions may require additional permissions
|
|
552
|
+
- ClickHouse may require specific permissions for system tables
|
|
553
|
+
|
|
554
|
+
### Large Result Sets
|
|
555
|
+
- Use the `limit` parameter to control result size
|
|
556
|
+
- The server automatically limits results to prevent memory issues
|
|
557
|
+
- For large analyses, consider using more specific queries
|
|
558
|
+
|
|
559
|
+
## Contributing
|
|
560
|
+
|
|
561
|
+
Contributions are welcome! The server is designed to be read-only and safe by default. Any new features should maintain these safety guarantees.
|
|
562
|
+
|
|
563
|
+
## License
|
|
564
|
+
|
|
565
|
+
MIT License - See LICENSE file for details
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
db_connect_mcp/__init__.py,sha256=HBy0IhP1gAQEGVscnMsyBtjLGLGx2Utd4SwOMMQijBw,816
|
|
2
|
+
db_connect_mcp/__main__.py,sha256=uUbJtogwzOjQatBlmM6Vf0FLYBrtlN1LB25M0DIp25M,361
|
|
3
|
+
db_connect_mcp/server.py,sha256=-k7594K5UeAeIUpuzU5uwLPO793lT8R0L1zwlotbfnQ,17350
|
|
4
|
+
db_connect_mcp/adapters/__init__.py,sha256=f89QV2q4-7iqRyqQEMz7gQ4DbEJcVSzreYF1gUQdf5c,1743
|
|
5
|
+
db_connect_mcp/adapters/base.py,sha256=HVeS-1Pd22ZOGtrA4u2yQT7d6H4zmWTI14bOOjbvBcU,3916
|
|
6
|
+
db_connect_mcp/adapters/clickhouse.py,sha256=BvSbIJGZZtIIrd6FziVxA6Y-vshqb3Xc_WLuehGdKU0,10619
|
|
7
|
+
db_connect_mcp/adapters/mysql.py,sha256=U-kQ80JiYno5KKXfWgDiXoArine_JqpjHXKHoMq9R_Q,9914
|
|
8
|
+
db_connect_mcp/adapters/postgresql.py,sha256=cLl8AhAc1hquUg-oduhYut9omE_zEkEjBQZBYqpkPl0,12592
|
|
9
|
+
db_connect_mcp/core/__init__.py,sha256=YR6uDC0yzgaJXldsGQDMxBneA8e5K1A4LHyPbSy1IgM,313
|
|
10
|
+
db_connect_mcp/core/analyzer.py,sha256=P7APjkhaoTElTfV9Vp3hvom3fXujVEdXSpSmAxkuE_k,3385
|
|
11
|
+
db_connect_mcp/core/connection.py,sha256=zNDTGOMqeSncZGFxbJXmsO4PitvEB6fUDVgucCJmDuo,13853
|
|
12
|
+
db_connect_mcp/core/executor.py,sha256=IOoFEO1mYm5wlUvsqlZM1OarDExle5d_ESmZ100cdUI,7689
|
|
13
|
+
db_connect_mcp/core/inspector.py,sha256=PP6JyLKD9F5fENmjBynqKmzjg72h1ShBfVqzcu9fdbk,12915
|
|
14
|
+
db_connect_mcp/models/__init__.py,sha256=ghBtsv7zZ-0A6ZINPu7H8YdY-Cyre00g1iMvqWGUN6s,603
|
|
15
|
+
db_connect_mcp/models/capabilities.py,sha256=kAlbGtAdbZVTM1iKN7bxV-W4dY0snZatupRp-71nB-A,2917
|
|
16
|
+
db_connect_mcp/models/config.py,sha256=EdrHqFt_ojra7AWzhG-378gtbrbCq5ldZ2sT4qZk_Es,16912
|
|
17
|
+
db_connect_mcp/models/database.py,sha256=MEg5pimkkvMhdre7u2oVWRyuaJToja26Rjro-QCfICQ,4258
|
|
18
|
+
db_connect_mcp/models/query.py,sha256=FazyV6pWEJFUDlYPswOmCGJTUgT14f9xfzQHZhxh9n0,4398
|
|
19
|
+
db_connect_mcp/models/statistics.py,sha256=ii_UqybC9L5P1DF4KN0XOnG49s4cmYlOdWDAdkVhqUc,6208
|
|
20
|
+
db_connect_mcp/models/table.py,sha256=v1HhItb2UqS9QpAfMgDoDyU_6xDgvy4r3BlEE7QliSs,8445
|
|
21
|
+
db_connect_mcp-0.1.0.dist-info/METADATA,sha256=QqaoYT-xLEdVBeINqV1wxk0SC_fmZi7FAczZq_Bv6-8,18111
|
|
22
|
+
db_connect_mcp-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
23
|
+
db_connect_mcp-0.1.0.dist-info/entry_points.txt,sha256=UoN-St_MnE5kk4ZDEvzMi6dCvNi0CmvsqbPpYNxJOac,62
|
|
24
|
+
db_connect_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=c71UYlLh5ubuIlgVlM3EMkFdhWxTIULtUx_a8KOhI8w,1065
|
|
25
|
+
db_connect_mcp-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Yuri Gui
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|