Command Palette

Search for a command to run...

UnylyUnyly
Browse all

Database Operations

FreeNot checked

Enables database inspection, backup/restore, analysis, and querying, plus media library and Windows Registry management via MCP tools.

GitHubEmbed

About

Enables database inspection, backup/restore, analysis, and querying, plus media library and Windows Registry management via MCP tools.

README

FastMCP Version Ruff Linted with Biome Built with Just

Version Python FastMCP License

Database Operations MCP

Just Ruff Python FastMCP

📖 Installation Guide — quick start, manual setup, and troubleshooting 🧭 Onboarding — no wrappee/account needed; sanity-check steps

FastMCP 3.3 MCP server for database operations on Windows. Includes MCP prompts and a bundled database-expert skill. Browser bookmark management lives in bookmarks-mcp.

⚠️ NSIS Installer Status: The Tauri NSIS desktop installer is currently non-functional due to a PyInstaller --onefile compatibility issue with fastmcp's OpenTelemetry dependency chain. A --onedir fix is in progress. The stdio and HTTP servers work normally.

Scope

  • Database tools (inspection, backup/restore, analysis, Windows application databases)
  • Media library tools (Calibre, Plex)
  • Windows Registry and system utilities

Tools Overview

Portmanteau tools consolidate individual operations into unified interfaces.

Database Tools

  • db_connection - Database connection management portmanteau (consolidates connection_tools, init_tools)
    • Operations: list_supported, register, init, list, test, test_all, close, get_info, restore, set_active, get_active, get_preferences, set_preferences
  • db_operations - Query execution, transactions, batch operations, data export portmanteau (consolidates query_tools, data_tools)
    • Operations: execute_query, execute_transaction, execute_write, batch_insert, quick_data_sample, export_query_results
  • db_schema - Schema inspection, table/column/index analysis portmanteau (consolidates schema_tools)
    • Operations: list_databases, list_tables, describe_table, get_schema_diff
  • db_management - Database health checks, optimization, backup/restore portmanteau (consolidates management_tools)
  • db_fts - Full-text search with ranking and highlighting portmanteau (consolidates fts_tools)
  • db_analyzer - Comprehensive database analysis and diagnostics portmanteau
  • agentic_workflow_tool - FastMCP sampling-enabled agentic workflows for complex database operations
  • windows_system - Windows Registry, service status, system info portmanteau (consolidates registry_tools, windows_tools)

Media & Other Tools

  • media_library - Calibre & Plex library management portmanteau (consolidates calibre_tools, plex_tools, media_tools)
  • help_system - Interactive help and documentation portmanteau (consolidates help_tools)
  • system_init - System initialization and setup portmanteau

Deprecated Tools (Use Portmanteau Equivalents)

Individual tools are deprecated but kept for backwards compatibility. Migration paths:

  • connection_tools.* db_connection(operation='...')
  • init_tools.* db_connection(operation='...')
  • query_tools.* db_operations(operation='...')
  • data_tools.* db_operations(operation='...')
  • schema_tools.* db_schema(operation='...')
  • management_tools.* db_management(operation='...')
  • fts_tools.* db_fts(operation='...')
  • calibre_tools.* media_library(operation='...')
  • plex_tools.* media_library(operation='...')
  • registry_tools.* windows_system(operation='...')
  • windows_tools.* windows_system(operation='...')

See individual tool files in src/database_operations_mcp/tools/ for complete API documentation.

Core Database Features

  • SQLite utilities: open/read, schema introspection, queries, export
  • Backup and restore helpers for common Windows application databases
  • Windows paths helpers (browser history DBs, Outlook, etc.)
  • Safety helpers (file locks, status checks) with clear error messages
  • MCP tools organized under src/database_operations_mcp/tools/

Project Layout

database-operations-mcp/
 src/
    database_operations_mcp/
        main.py                      # MCP server entry
        config/
           mcp_config.py            # shared MCP instance
        tools/                     # portmanteau + atomic DB tools
        services/database/         # DB connectors
 tests/
 web_sota/                        # React dashboard (optional)
 README.md

Packaging & Distribution

This repository is SOTA 2026 compliant and uses the officially validated @anthropic-ai/mcpb workflow for distribution.

Pack Extension

To generate a .mcpb distribution bundle with complete source code and automated build exclusions:

# SOTA 2026 standard pack command
mcpb pack . dist/database-operations-mcp.mcpb

Quick Start

git clone https://github.com/sandraschi/database-operations-mcp
cd database-operations-mcp
just

This opens an interactive dashboard showing all available commands. Run just bootstrap to install dependencies, then just serve or just dev to start.

Manual Setup

If you don't have just installed:

Install Zed Extension

This repository includes a Zed extension for native integration with the Zed editor.

Prerequisites

  • Rust toolchain installed (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh)

Build the Extension

cd zed-extension
cargo build --release --target wasm32-wasip1

Install in Zed

  1. Open Zed
  2. Go to Extensions Install Dev Extension
  3. Navigate to the repository and select: zed-extension/extension.toml
  4. The Database Operations MCP extension will be installed and loaded

Note: The extension runs the MCP server from the parent directory, so make sure you're in the correct repository location.

Zed Extension Features

  • MCP server integration within Zed
  • Database operations accessible from Zed's AI assistant
  • Context server management
  • Integration with Zed's codebase understanding

Configure in Cursor / Claude (recommended)

Transports: stdio and HTTP

  • Default: dual (both stdio and HTTP) unless overridden
  • Override via env: set MCP_TRANSPORT=stdio|http|dual
  • HTTP host/port via MCP_HOST (default 0.0.0.0) and MCP_PORT (default 8000)
  • CLI flags: --stdio, --http, --dual
# HTTP only on port 3210
$env:MCP_TRANSPORT = "http"
$env:MCP_PORT = "3210"
uv run python -m database_operations_mcp.main --http

# Dual mode (stdio + HTTP) with custom host/port
$env:MCP_TRANSPORT = "dual"
$env:MCP_HOST = "127.0.0.1"
$env:MCP_PORT = "9000"
uv run python -m database_operations_mcp.main --dual

Add the server to your MCP config (%USERPROFILE%\AppData\Roaming\Cursor\.cursor\mcp.json or equivalent):

{
  "mcpServers": {
    "database-operations-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "database_operations_mcp.main"],
      "env": { "LOG_LEVEL": "INFO" }
    }
  }
}

Development

For Python development setup, testing, and contribution guidelines, see README-python.md.

Installation

Prerequisites

  • uv installed (RECOMMENDED)
  • Python 3.12+

Quick Start

Run immediately via uvx:

uvx database-operations-mcp

Claude Desktop Integration

Add to your claude_desktop_config.json:

"mcpServers": {
  "database-operations": {
    "command": "uv",
    "args": ["--directory", "D:/Dev/repos/database-operations-mcp", "run", "database-operations-mcp"]
  }
}

From PyPI (Recommended)

pip install database-operations-mcp

From GitHub Releases

# Direct wheel download
pip install https://github.com/sandraschi/database-operations-mcp/releases/download/v1.4.0/database_operations_mcp-1.4.0-py3-none-any.whl

# Or from git
pip install git+https://github.com/sandraschi/database-operations-mcp.git

For Claude Desktop (MCPB Package)

One-click install for Claude Desktop: download and run install.ps1 from the latest release (or drag-and-drop the database-operations-mcp.mcpb bundle from the same release):

  1. Download or build the latest .mcpb file.
  2. Open Claude Desktop Settings Extensions
  3. Drag and drop the .mcpb file
  4. Restart Claude Desktop

FastMCP 3.1.0 Features

This server uses FastMCP 3.1.0 capabilities:

Conversational Tool Returns

All tools return structured responses with natural language summaries alongside technical data.

Example Response:

{
  "success": true,
  "operation": "list_supported",
  "message": "I found 15 supported database types across 4 categories. You can connect to SQL databases (PostgreSQL, MySQL, SQLite), NoSQL databases (MongoDB), vector databases (ChromaDB), and more.",
  "databases_by_category": {...},
  "total_supported": 15,
  "categories": ["sql", "nosql", "vector", "graph"]
}

Sampling Capabilities

Supports agentic workflows where the LLM can orchestrate multi-step database operations without client round-trips.

Example Workflow:

result = await db_sampling_workflow(
    workflow_prompt="Analyze database performance, optimize slow queries, and generate a comprehensive report",
    available_operations=["analyze_performance", "optimize_queries", "generate_report"],
    max_iterations=10
)

Enhanced Error Handling

Error responses include recovery suggestions and context-aware guidance.

Example Error Response:

{
  "success": false,
  "operation": "execute_query",
  "message": "I encountered an error while executing your query. The connection to the database might have been lost.",
  "error": "Connection timeout after 30 seconds",
  "error_code": "CONNECTION_TIMEOUT",
  "suggestions": [
    "Check if the database server is running",
    "Verify network connectivity",
    "Try reconnecting using the 'test' operation"
  ]
}

Agentic Database Workflows

The db_sampling_workflow tool enables complex database operations that would previously require multiple round-trips:

  • Query optimization: Analyzes and optimizes slow queries
  • Schema migration planning: Plans and executes schema changes
  • Data quality assessment: Data validation and integrity checks
  • Performance analysis: Performance bottleneck detection and resolution

Requirements

  • Python 3.10+
  • FastMCP 3.1.0+
  • Persistence: py-key-value-aio[disk] for DiskStore (optional; in-memory fallback if not installed)
  • Database Drivers: chromadb, pymongo, psycopg2-binary, duckdb, aiomysql, redis
  • Utilities: aiohttp, rich, psutil

🛡️ Industrial Quality Stack

This project adheres to SOTA 14.1 industrial standards for high-fidelity agentic orchestration:

  • Python (Core): Ruff for linting and formatting. Zero-tolerance for print statements in core handlers (T201).
  • Webapp (UI): Biome for sub-millisecond linting. Strict noConsoleLog enforcement.
  • Protocol Compliance: Hardened stdout/stderr isolation to ensure crash-resistant JSON-RPC communication.
  • Automation: Justfile recipes for all fleet operations (just lint, just fix, just dev).
  • Security: Automated audits via bandit and safety.

Webapp Dashboard

This MCP server includes a web interface (FastMCP 3.1.0 gateway) for monitoring and tool execution.

  • Frontend: port 10708 (Vite dev server)
  • Backend: port 10709 (FastAPI + MCP mounted at /mcp, REST at /api/tools)

To start the webapp:

  1. Navigate to the web_sota directory.
  2. Run .\start.ps1 (PowerShell; from repo root: cd web_sota; .\start.ps1).
  3. Open http://localhost:10708 in your browser.

Prompts and skills (FastMCP 3.1.0)

  • MCP prompt database_expert: Clients can call get_prompt("database_expert", arguments={"focus": "general"|"sql"|"connections"|"export"}) to receive instruction text to inject so the LLM acts as a database expert using this server's tools. Use when you want the assistant to follow connection/schema/query/export practices without reading this README.
  • Bundled skill database-expert: Exposed as MCP resources under the skill:// scheme. Clients that support MCP resources can read skill://database-expert/SKILL.md (and manifest/supporting files) for the same expert guidance. The skill lives in src/database_operations_mcp/skills/database-expert/ and is registered via the FastMCP Skills provider.

See [FastMCP Prompts](https://goFastMCP 3.1.0com/servers/prompts) and [Skills Provider](https://goFastMCP 3.1.0com/servers/providers/skills) for the framework docs.

Persistence

Connection state and preferences are persisted across restarts using py-key-value-aio[disk] (DiskStore).

  • Storage location: %APPDATA%\database-operations-mcp (Windows), ~/Library/Application Support/database-operations-mcp (macOS), ~/.local/share/database-operations-mcp (Linux).
  • Persisted data: Saved database connections, active connection id, user preferences (e.g. default page size), restore state, and schema cache.
  • Initialization: Storage is initialized in server lifespan; if the optional [disk] extra is not installed, the server falls back to in-memory storage and logs a warning.
  • Development: Set ENABLE_PASSWORD_STORAGE=1 only in dev; it allows storing connection passwords (insecure, not for production).

from github.com/sandraschi/database-operations-mcp

Installing Database Operations

This server has no published package — it is built from source. Open the repository and follow its README.

▸ github.com/sandraschi/database-operations-mcp

FAQ

Is Database Operations MCP free?

Yes, Database Operations MCP is free — one-click install via Unyly at no cost.

Does Database Operations need an API key?

No, Database Operations runs without API keys or environment variables.

Is Database Operations hosted or self-hosted?

Self-hosted: the server runs locally on your machine via the install command above.

How do I install Database Operations in Claude Desktop, Claude Code or Cursor?

Open Database Operations on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.

Related MCPs

Compare Database Operations with

Not sure what to pick?

Find your stack in 60 seconds

Author?

Embed badge for your README

Browse similar

All data MCPs