Labsco
ahmetbarut logo

Database Server

★ 5

from ahmetbarut

A Model Context Protocol (MCP) server that provides multi-database query execution capabilities with support for SQLite, PostgreSQL, and MySQL databases. Includes a built-in Web UI for managing database connections.

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#database#git#security

MCP Database Server

A Model Context Protocol (MCP) server that provides multi-database query execution capabilities with support for SQLite, PostgreSQL, and MySQL databases. Includes a built-in Web UI for managing database connections.

NPM Package

Available on NPM: @ahmetbarut/mcp-database-server

# Use with npx (no installation required)
npx @ahmetbarut/mcp-database-server

# Or install globally
npm install -g @ahmetbarut/mcp-database-server

Features

  • Multi-Database Support: SQLite, PostgreSQL, and MySQL with real connections
  • Web UI: Built-in browser interface for managing database connections
  • SQLite Config Store: All connection configs persisted locally in ~/.mcp-database-server/connections.db
  • MCP Protocol Compliance: Full JSON-RPC implementation with complete tool support
  • Smart Auto-Detection: Automatically selects single active connection for queries
  • Connection Recovery: Retry failed connections with detailed error reporting
  • Security First: Parameterized queries, SQL injection protection, audit logging
  • SSL Support: Configurable SSL per connection
  • Type Safety: Full TypeScript implementation with Zod validation
  • Node.js v23 Compatible: Works with latest Node.js versions

Web UI

The built-in Web UI provides a visual interface for managing database connections:

  • Add/Edit/Delete database connections (SQLite, PostgreSQL, MySQL)
  • Test connections before saving
  • SSL toggle for network databases
  • Persistent storage — connections survive server restarts

Access it at http://localhost:3693 when the server is running.

Environment Variables

VariableDefaultDescription
WEB_UI_PORT3693Web UI port
WEB_UI_ENABLEDtrueEnable/disable Web UI
LOG_LEVELinfoLogging level (debug, info, warn, error)

MCP Tools

execute_query

Execute SQL queries on a database connection with parameterized query support.

{
  "connection_name": "my-postgres",
  "query": "SELECT * FROM users WHERE status = $1",
  "parameters": ["active"]
}

list_databases

List databases from a specific connection or all configured connections. Supports smart auto-detection when only one connection is active.

{
  "connection_name": "my-postgres"
}

list_connections

List all database connections with status and details.

{
  "include_credentials": false
}

retry_failed_connections

Retry failed database connections.

{
  "connection_name": "my-postgres"
}

Development

# Clone the repository
git clone https://github.com/ahmetbarut/mcp-database-server.git
cd mcp-database-server

# Install dependencies
npm install

# Development mode (hot-reload)
npm run dev

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Type check
npm run type-check

Project Structure

mcp-database-server/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── server/
│   │   └── mcp-server.ts     # MCP server, tool handlers
│   ├── database/
│   │   ├── base.ts           # Abstract base driver
│   │   ├── factory.ts        # Driver factory & connection manager
│   │   └── drivers/          # SQLite, PostgreSQL, MySQL drivers
│   ├── config/
│   │   ├── settings.ts       # Config manager (loads from SQLite store)
│   │   └── config-store.ts   # SQLite-backed connection storage
│   ├── web/
│   │   ├── web-server.ts     # HTTP server for Web UI
│   │   ├── routes.ts         # REST API endpoints
│   │   └── ui.ts             # Embedded HTML/CSS/JS interface
│   ├── types/                # TypeScript types & Zod schemas
│   └── utils/                # Logger, exceptions, helpers
├── tests/unit/               # Jest test suites
└── dist/                     # Compiled output

Architecture

npx @ahmetbarut/mcp-database-server
    │
    ├── MCPDatabaseServer
    │   ├── MCP stdio transport (JSON-RPC)
    │   ├── DatabaseConnectionManager
    │   └── WebUIServer (http://localhost:3693)
    │
    └── ConnectionConfigStore (~/.mcp-database-server/connections.db)
        └── SQLite database with connection configs
  1. Config Store loads saved connections from local SQLite DB
  2. Connection Manager initializes database drivers for each config
  3. MCP Server exposes tools via JSON-RPC over stdio
  4. Web UI provides browser-based CRUD for connections via REST API

Security

  • Parameterized queries — prevents SQL injection
  • Credential masking — passwords hidden in list_connections output
  • Audit logging — all operations logged via Winston
  • Input validation — Zod schemas for all configuration

Testing

Test Suites: 2 passed, 2 total
Tests:       23 passed, 23 total
npm test               # Run all tests
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report

Support

For issues and questions, use the GitHub issue tracker.