Database Tools MCP Server
An MCP (Model Context Protocol) server that provides database exploration and query tools for AI assistants. This server enables safe SQL querying and database schema exploration with built-in security features.
Features
- Table List Explorer: List all tables and views in a database
- Table Details Explorer: Get detailed schema information and sample data for specific tables
- Query Engine: Execute read-only SQL queries with safety features and timeouts
Installation
No installation required! Use uvx to run directly:
uvx oriona-database-tools
Quick Start
-
No installation needed - uvx runs the package directly
-
Set your database URL:
# PostgreSQL export DATABASE_URL="postgresql://user:password@localhost:5432/mydb" # SQL Server export DATABASE_URL="mssql+pymssql://user:password@localhost:1433/mydb" # MySQL export DATABASE_URL="mysql+pymysql://user:password@localhost:3306/mydb" # SQLite export DATABASE_URL="sqlite:///path/to/database.db"
-
Add to Claude Desktop (see configuration below)
Claude Desktop Configuration
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"database-tools": {
"command": "uvx",
"args": ["oriona-database-tools"],
"env": {
"DATABASE_URL": "postgresql://user:password@localhost:5432/mydb",
"TABLE_WHITELIST": "users,orders,products",
"TABLE_BLACKLIST": "api_keys,secrets"
}
}
}
}
Security Note: Always use a read-only database user for the MCP server to ensure data safety.
Available Tools
1. list_tables
List all tables and views in a database.
Parameters:
include_views(boolean, optional): Include database views in the list (default: true)
Example:
{
"tool": "list_tables",
"arguments": {
"include_views": true
}
}
2. explore_table
Get detailed information about a specific table including schema, foreign keys, and sample data.
Parameters:
table_name(string, required): The name of the table to analyzesample_size(integer, optional): Number of sample rows to retrieve (0-100, default: 3)
Example:
{
"tool": "explore_table",
"arguments": {
"table_name": "customers",
"sample_size": 5
}
}
3. query_database_readonly
Execute read-only SELECT queries with safety features.
Parameters:
query(string, required): The SQL query to execute (SELECT only)timeout_seconds(integer, optional): Maximum query execution time in seconds (default: 30)max_rows(integer, optional): Maximum number of rows to return (0 for unlimited, default: 100)
Example:
{
"tool": "query_database_readonly",
"arguments": {
"query": "SELECT * FROM orders WHERE created_at > '2024-01-01' LIMIT 10",
"timeout_seconds": 30,
"max_rows": 100
}
}
Supported Databases
- PostgreSQL (recommended)
- MySQL
- Microsoft SQL Server
- SQLite
- BigQuery (Google Cloud)
- Any SQLAlchemy-supported database
Security Features
- Read-only queries: Only SELECT and WITH queries are allowed
- Query timeout: Configurable timeout to prevent long-running queries
- Row limits: Default limit of 100 rows per query (configurable)
- Connection pooling: Efficient connection management with pool recycling
- URI sanitization: Automatic conversion of legacy postgres:// to postgresql://
- Table filtering: Whitelist/blacklist specific tables to control access
Environment Variables
Required:
DATABASE_URL: The database connection URL (e.g.,postgresql://user:pass@localhost:5432/mydb)
Optional:
DATABASE_TOOLS_LOG_LEVEL: Set logging level (default: INFO)DATABASE_TOOLS_MAX_CONNECTIONS: Maximum database connections per pool (default: 5)TABLE_WHITELIST: Comma-separated list of allowed tables (e.g.,users,orders,products)TABLE_BLACKLIST: Comma-separated list of forbidden tables (e.g.,secrets,sensitive_data)
BigQuery-specific (when using BigQuery):
BIGQUERY_PROJECT_ID: Google Cloud project ID (required for BigQuery)BIGQUERY_CREDENTIALS_BASE64: Base64 encoded service account JSON (optional, falls back to default credentials)BIGQUERY_DATASET: Default dataset name (optional, if not specified, queries all accessible datasets)BIGQUERY_LOCATION: BigQuery location/region (default: US)
Microsoft SQL Server Setup
{
"mcpServers": {
"database-tools": {
"command": "uvx",
"args": ["oriona-database-tools"],
"env": {
"DATABASE_URL": "mssql+pymssql://{{username}}:{{password}}@{{host}}:{{port}}/database"
}
}
}
}
Connection String Examples:
# Basic connection
mssql+pymssql://user:password@localhost:1433/mydb
BigQuery Setup
Authentication
Option 1: Base64 Encoded Service Account (Recommended)
- Create a service account in Google Cloud Console
- Download the JSON key file
- Encode to base64:
base64 -i /path/to/service-account.json
- Configure Claude Desktop:
{ "mcpServers": { "database-tools": { "command": "uvx", "args": ["oriona-database-tools"], "env": { "BIGQUERY_PROJECT_ID": "your-project-id", "BIGQUERY_CREDENTIALS_BASE64": "eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii...", "BIGQUERY_DATASET": "your_dataset" } } } }
Option 2: Default Credentials (Fallback)
If you have the Google Cloud CLI installed and authenticated:
gcloud auth application-default login
Then configure without credentials:
{
"mcpServers": {
"database-tools": {
"command": "uvx",
"args": ["oriona-database-tools"],
"env": {
"BIGQUERY_PROJECT_ID": "your-project-id",
"BIGQUERY_DATASET": "your_dataset"
}
}
}
}
Dataset Configuration
- Specific dataset: Set
BIGQUERY_DATASETto limit access to one dataset - All datasets: Leave
BIGQUERY_DATASETunset to access all datasets (tables will be prefixed withdataset.table)
Required Permissions
Your service account needs these BigQuery permissions:
bigquery.datasets.getbigquery.tables.listbigquery.tables.getbigquery.tables.getDatabigquery.jobs.create
Table Filtering
You can control which tables are accessible through the MCP server using whitelist and blacklist configurations:
Whitelist Mode
When TABLE_WHITELIST is set, only the specified tables will be accessible:
{
"env": {
"DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb",
"TABLE_WHITELIST": "users,orders,products"
}
}
In this example, only users, orders, and products tables can be accessed.
Blacklist Mode
When TABLE_BLACKLIST is set, the specified tables will be blocked:
{
"env": {
"DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb",
"TABLE_BLACKLIST": "api_keys,user_passwords,audit_logs"
}
}
In this example, api_keys, user_passwords, and audit_logs tables cannot be accessed.
Filtering Behavior
- Filtered tables won't appear in
list_tablesresults - Attempts to access filtered tables with
explore_tablewill return an access denied error - Table names are case-insensitive (e.g.,
Usersandusersare treated the same)
Error Handling
The server returns structured error responses:
{
"error": "Error message",
"error_type": "ExceptionType",
"recommendation": "Suggested action"
}
Common errors:
- Table/column not found: Check table names with
list_tables - Query timeout: Reduce query complexity or increase timeout
- Permission denied: Verify database credentials
Metadata
Release files for oriona-database-tools 0.4.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| oriona_database_tools-0.4.6.tar.gz | 143.0 kB | Without provenance | Details for oriona_database_tools-0.4.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| oriona_database_tools-0.4.6-py3-none-any.whl | Python 3 | none | any | Details for oriona_database_tools-0.4.6-py3-none-any.whl |
Total release size: 160.0 kB
Release files / oriona_database_tools-0.4.6.tar.gz
| Download URL | oriona_database_tools-0.4.6.tar.gz |
|---|---|
| Size | 143.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
44a94b23dd2b954d3a20a570839f4fedf948584981ef008b21e26f8a1a867cd2
|
|
BLAKE2b-256 checksum How to use checksums |
fdb265b62a4631e5df8cb127b234a1f5469118ab8957e25942c15473cbc18225
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.5
|
Release files / oriona_database_tools-0.4.6-py3-none-any.whl
| Download URL | oriona_database_tools-0.4.6-py3-none-any.whl |
|---|---|
| Size | 17.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
de89690fc64dc0463d76db1f5ace431476612a4269e635545d945010e13053bd
|
|
BLAKE2b-256 checksum How to use checksums |
14495f1ba7a90c9580463ad87086dc4c4593393f3fce8cc0520a11b6498f58a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.5
|
Security for oriona-database-tools 0.4.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.