Abdulmumin1/db-mcp

Database MCP Server

A Model Context Protocol (MCP) server that provides secure, read-only access to databases through AI assistants. This server allows MCP-compatible clients to execute SQL queries against databases while enforcing strict read-only operations.

Features

• Secure Read-Only Queries: Only allows SELECT and WITH statements, blocking all write operations
• Multiple Database Support: Currently supports PostgreSQL and MySQL
• MCP Protocol: Fully compatible with the Model Context Protocol for seamless AI integration
• Environment-Based Configuration: Easy setup through environment variables
• TypeScript: Built with TypeScript for type safety and maintainability

Supported Adapters

• PostgreSQL (DB_TYPE=postgres)
• MySQL (DB_TYPE=mysql)

Installation

Prerequisites

• Node.js 18+
• A PostgreSQL or MySQL database

Install Dependencies

npm install
# or
pnpm install

Build the Server

npm run build
# or
pnpm build

This creates an executable build/index.js file.

Configuration

Configure the server using environment variables:

Example Configuration

For PostgreSQL:

export DB_TYPE=postgres
export DB_HOST=localhost
export DB_PORT=5432
export DB_USER=myuser
export DB_PASSWORD=mypassword
export DB_DATABASE=mydatabase

For MySQL:

export DB_TYPE=mysql
export DB_HOST=localhost
export DB_PORT=3306
export DB_USER=myuser
export DB_PASSWORD=mypassword
export DB_DATABASE=mydatabase

Usage

Running the Server

After building and configuring environment variables:

node build/index.js

The server will start and listen on stdin/stdout for MCP protocol messages.

MCP Client Integration

This server is designed to work with MCP-compatible clients. The server provides a single tool:

run_query

Executes a secure, read-only SQL query against the configured database.

Input:

• query (string): The read-only SQL query to execute (must start with SELECT or WITH)

Output:

• JSON response with query results or error information

Security

This server implements several security measures:

• Read-Only Enforcement: Queries are validated to ensure they only contain SELECT or WITH statements
• Keyword Filtering: Blocks queries containing write operations (INSERT, UPDATE, DELETE, etc.)
• Connection Isolation: Each query uses a separate database connection that is properly closed
• No DDL Operations: Prevents schema modifications and administrative commands

Development

Project Structure

src/
├── index.ts              # Main server implementation
└── adapters/
    ├── index.ts          # Adapter exports and factory
    ├── base.ts           # Abstract adapter and validation
    ├── postgres.ts       # PostgreSQL adapter
    └── mysql.ts          # MySQL adapter
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
└── README.md              # This file

Adding New Database Adapters

To add support for a new database type:

1. Create a new file in src/adapters/ (e.g., sqlite.ts)
2. Create a new adapter class extending DBAdapter from ./base.js
3. Implement the required methods: connect() and executeReadOnlyQuery()
4. Export the class from the new file
5. Add the adapter to the adapterFactory object in src/adapters/index.ts
6. Update the dependencies in package.json if needed

Example:

// src/adapters/sqlite.ts
import { DBAdapter } from './base.js';

export class SqliteAdapter extends DBAdapter {
  async connect() {
    // Implementation
  }

  async executeReadOnlyQuery(query: string) {
    // Implementation
  }
}

// src/adapters/index.ts
import { SqliteAdapter } from './sqlite.js';

export const adapterFactory: Record<string, new (details: ConnectionDetails) => DBAdapter> = {
  'postgres': PostgresAdapter,
  'mysql': MySqlAdapter,
  'sqlite': SqliteAdapter,  // New adapter
};

Testing

Run the linter:

npm run lint

Fix linting issues:

npm run lint:fix

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

ISC License

Dependencies

• @modelcontextprotocol/sdk - MCP protocol implementation
• pg - PostgreSQL client
• mysql2 - MySQL client
• zod - Schema validation