mcp-database 0.1.0__tar.gz

mcp_database-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+.env
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+*.db
+*.sqlite
+*.sqlite3
+.DS_Store

mcp_database-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mergewall Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_database-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: mcp-database
+Version: 0.1.0
+Summary: MCP server for multi-database access — SQLite, PostgreSQL, MySQL. Query, inspect schema, and manage databases through Claude.
+Author: Mergewall Team
+License: MIT
+License-File: LICENSE
+Keywords: claude,database,mcp,model-context-protocol,mysql,postgresql,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: psycopg2-binary>=2.9.0; extra == 'all'
+Requires-Dist: pymysql>=1.1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1.0; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9.0; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# mcp-database
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-compatible-orange)](https://modelcontextprotocol.io)
+
+**MCP server for multi-database access — query, inspect schema, and manage SQLite, PostgreSQL, and MySQL databases through Claude.**
+
+## Why mcp-database?
+
+| Problem | Solution |
+|---------|----------|
+| Need to query a database from Claude Code / Claude Desktop | One MCP server, multiple database support |
+| Existing database MCP servers are JS/Go only | Pure Python, uses official `mcp` SDK |
+| Worried about accidental writes | Read-only by default, writes opt-in |
+| Don't know the schema | Built-in schema inspection, table info, search |
+
+## Quick Start
+
+```bash
+# Install
+pip install mcp-database
+
+# Run with a SQLite database
+MCP_DATABASE_URL=sqlite:///path/to/your.db mcp-database
+```
+
+### Claude Code Integration
+
+```bash
+# Add to Claude Code
+claude mcp add mcp-database -- mcp-database
+
+# Or with a specific database
+claude mcp add mcp-database -e MCP_DATABASE_URL=sqlite:///path/to/db.sqlite -- mcp-database
+```
+
+### Claude Desktop Integration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "mcp-database",
+      "env": {
+        "MCP_DATABASE_URL": "sqlite:///path/to/your.db"
+      }
+    }
+  }
+}
+```
+
+## Supported Databases
+
+| Database | Status | Install |
+|----------|--------|---------|
+| **SQLite** | Built-in | `pip install mcp-database` |
+| **PostgreSQL** | Optional | `pip install 'mcp-database[postgres]'` |
+| **MySQL** | Optional | `pip install 'mcp-database[mysql]'` |
+| **All** | Optional | `pip install 'mcp-database[all]'` |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP_DATABASE_URL` | `sqlite:///:memory:` | Database connection URL |
+| `MCP_DATABASE_TYPE` | `sqlite` | Database type: `sqlite`, `postgresql`, `mysql` |
+| `MCP_DATABASE_READ_ONLY` | `true` | Enable read-only mode |
+| `MCP_MAX_ROWS` | `100` | Maximum rows returned per query |
+
+### Connection URLs
+
+```bash
+# SQLite
+MCP_DATABASE_URL=sqlite:///path/to/db.sqlite
+MCP_DATABASE_URL=sqlite:///:memory:
+
+# PostgreSQL
+MCP_DATABASE_URL=postgres://user:password@localhost:5432/mydb
+MCP_DATABASE_TYPE=postgresql
+
+# MySQL
+MCP_DATABASE_URL=mysql://user:password@localhost:3306/mydb
+MCP_DATABASE_TYPE=mysql
+```
+
+## Available Tools
+
+Once connected, Claude can use these tools:
+
+| Tool | Description |
+|------|-------------|
+| `list_databases` | List all configured database connections |
+| `list_tables` | List all tables in a database |
+| `get_table_info` | Get detailed table info (columns, types, row count) |
+| `get_schema` | Get full database schema (CREATE TABLE statements) |
+| `query` | Execute a read-only SQL query (SELECT, SHOW, DESCRIBE) |
+| `execute` | Execute a write statement (INSERT, UPDATE, DELETE) — opt-in only |
+| `sample_rows` | Get sample rows from a table |
+| `search_tables` | Search for tables or columns by keyword |
+
+## Examples
+
+Ask Claude things like:
+
+- "What tables are in my database?"
+- "Show me the schema for the users table"
+- "Query the top 10 orders by amount"
+- "Find all columns related to 'email'"
+- "Sample some rows from the products table"
+
+## Security
+
+- **Read-only by default** — queries are safe, no data modification
+- **Write opt-in** — set `allow_writes=True` and `MCP_DATABASE_READ_ONLY=false` to enable
+- **Read-only detection** — write tool rejects SELECT statements (use `query` instead)
+- **Row limits** — configurable max rows to prevent accidental large result sets
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/Jansen003/mcp-database.git
+cd mcp-database
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run with Inspector UI
+mcp dev src/mcp_database/server.py
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_database-0.1.0/README.md

@@ -0,0 +1,140 @@
+# mcp-database
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-compatible-orange)](https://modelcontextprotocol.io)
+
+**MCP server for multi-database access — query, inspect schema, and manage SQLite, PostgreSQL, and MySQL databases through Claude.**
+
+## Why mcp-database?
+
+| Problem | Solution |
+|---------|----------|
+| Need to query a database from Claude Code / Claude Desktop | One MCP server, multiple database support |
+| Existing database MCP servers are JS/Go only | Pure Python, uses official `mcp` SDK |
+| Worried about accidental writes | Read-only by default, writes opt-in |
+| Don't know the schema | Built-in schema inspection, table info, search |
+
+## Quick Start
+
+```bash
+# Install
+pip install mcp-database
+
+# Run with a SQLite database
+MCP_DATABASE_URL=sqlite:///path/to/your.db mcp-database
+```
+
+### Claude Code Integration
+
+```bash
+# Add to Claude Code
+claude mcp add mcp-database -- mcp-database
+
+# Or with a specific database
+claude mcp add mcp-database -e MCP_DATABASE_URL=sqlite:///path/to/db.sqlite -- mcp-database
+```
+
+### Claude Desktop Integration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "mcp-database",
+      "env": {
+        "MCP_DATABASE_URL": "sqlite:///path/to/your.db"
+      }
+    }
+  }
+}
+```
+
+## Supported Databases
+
+| Database | Status | Install |
+|----------|--------|---------|
+| **SQLite** | Built-in | `pip install mcp-database` |
+| **PostgreSQL** | Optional | `pip install 'mcp-database[postgres]'` |
+| **MySQL** | Optional | `pip install 'mcp-database[mysql]'` |
+| **All** | Optional | `pip install 'mcp-database[all]'` |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP_DATABASE_URL` | `sqlite:///:memory:` | Database connection URL |
+| `MCP_DATABASE_TYPE` | `sqlite` | Database type: `sqlite`, `postgresql`, `mysql` |
+| `MCP_DATABASE_READ_ONLY` | `true` | Enable read-only mode |
+| `MCP_MAX_ROWS` | `100` | Maximum rows returned per query |
+
+### Connection URLs
+
+```bash
+# SQLite
+MCP_DATABASE_URL=sqlite:///path/to/db.sqlite
+MCP_DATABASE_URL=sqlite:///:memory:
+
+# PostgreSQL
+MCP_DATABASE_URL=postgres://user:password@localhost:5432/mydb
+MCP_DATABASE_TYPE=postgresql
+
+# MySQL
+MCP_DATABASE_URL=mysql://user:password@localhost:3306/mydb
+MCP_DATABASE_TYPE=mysql
+```
+
+## Available Tools
+
+Once connected, Claude can use these tools:
+
+| Tool | Description |
+|------|-------------|
+| `list_databases` | List all configured database connections |
+| `list_tables` | List all tables in a database |
+| `get_table_info` | Get detailed table info (columns, types, row count) |
+| `get_schema` | Get full database schema (CREATE TABLE statements) |
+| `query` | Execute a read-only SQL query (SELECT, SHOW, DESCRIBE) |
+| `execute` | Execute a write statement (INSERT, UPDATE, DELETE) — opt-in only |
+| `sample_rows` | Get sample rows from a table |
+| `search_tables` | Search for tables or columns by keyword |
+
+## Examples
+
+Ask Claude things like:
+
+- "What tables are in my database?"
+- "Show me the schema for the users table"
+- "Query the top 10 orders by amount"
+- "Find all columns related to 'email'"
+- "Sample some rows from the products table"
+
+## Security
+
+- **Read-only by default** — queries are safe, no data modification
+- **Write opt-in** — set `allow_writes=True` and `MCP_DATABASE_READ_ONLY=false` to enable
+- **Read-only detection** — write tool rejects SELECT statements (use `query` instead)
+- **Row limits** — configurable max rows to prevent accidental large result sets
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/Jansen003/mcp-database.git
+cd mcp-database
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run with Inspector UI
+mcp dev src/mcp_database/server.py
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_database-0.1.0/README_zh.md

@@ -0,0 +1,158 @@
+# mcp-database
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-compatible-orange)](https://modelcontextprotocol.io)
+
+**多数据库 MCP 服务器 —— 让 Claude 直接查询、探索和管理你的 SQLite、PostgreSQL、MySQL 数据库。**
+
+[English](README.md) | 中文
+
+## 为什么需要 mcp-database？
+
+| 你的问题 | mcp-database 的解决方案 |
+|---------|----------------------|
+| 想在 Claude Code 里直接查数据库 | 一个 MCP 服务器，支持多种数据库 |
+| 现有的数据库 MCP 要么是 JS 要么是 Go | 纯 Python，基于官方 `mcp` SDK |
+| 担心 Claude 误操作数据 | 默认只读模式，写入需要显式开启 |
+| 不熟悉数据库结构 | 内置表结构探索、列信息、关键词搜索 |
+
+## 快速开始
+
+```bash
+# 安装
+pip install mcp-database
+
+# 连接 SQLite 数据库
+MCP_DATABASE_URL=sqlite:///path/to/your.db mcp-database
+```
+
+### 接入 Claude Code
+
+```bash
+# 一行命令接入
+claude mcp add mcp-database -- mcp-database
+
+# 指定数据库文件
+claude mcp add mcp-database -e MCP_DATABASE_URL=sqlite:///path/to/db.sqlite -- mcp-database
+```
+
+### 接入 Claude Desktop
+
+在 `claude_desktop_config.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "mcp-database",
+      "env": {
+        "MCP_DATABASE_URL": "sqlite:///path/to/your.db"
+      }
+    }
+  }
+}
+```
+
+## 支持的数据库
+
+| 数据库 | 状态 | 安装方式 |
+|--------|------|----------|
+| **SQLite** | 内置 | `pip install mcp-database` |
+| **PostgreSQL** | 可选 | `pip install 'mcp-database[postgres]'` |
+| **MySQL** | 可选 | `pip install 'mcp-database[mysql]'` |
+| **全部** | 可选 | `pip install 'mcp-database[all]'` |
+
+## 配置方式
+
+### 环境变量
+
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| `MCP_DATABASE_URL` | `sqlite:///:memory:` | 数据库连接地址 |
+| `MCP_DATABASE_TYPE` | `sqlite` | 数据库类型：`sqlite`、`postgresql`、`mysql` |
+| `MCP_DATABASE_READ_ONLY` | `true` | 是否启用只读模式 |
+| `MCP_MAX_ROWS` | `100` | 单次查询最大返回行数 |
+
+### 连接地址格式
+
+```bash
+# SQLite
+MCP_DATABASE_URL=sqlite:///path/to/db.sqlite
+MCP_DATABASE_URL=sqlite:///:memory:
+
+# PostgreSQL
+MCP_DATABASE_URL=postgres://user:password@localhost:5432/mydb
+MCP_DATABASE_TYPE=postgresql
+
+# MySQL
+MCP_DATABASE_URL=mysql://user:password@localhost:3306/mydb
+MCP_DATABASE_TYPE=mysql
+```
+
+## 可用工具
+
+接入后，Claude 可以使用以下工具：
+
+| 工具名 | 说明 |
+|--------|------|
+| `list_databases` | 列出所有已配置的数据库连接 |
+| `list_tables` | 列出数据库中的所有表 |
+| `get_table_info` | 获取表的详细信息（列名、类型、行数） |
+| `get_schema` | 获取完整的数据库建表语句 |
+| `query` | 执行只读 SQL 查询（SELECT、SHOW、DESCRIBE） |
+| `execute` | 执行写入语句（INSERT、UPDATE、DELETE）—— 需手动开启 |
+| `sample_rows` | 获取表中的示例数据 |
+| `search_tables` | 按关键词搜索表名和列名 |
+
+## 使用示例
+
+你可以这样问 Claude：
+
+- "我的数据库里有哪些表？"
+- "看一下 users 表的结构"
+- "查询金额最大的 10 笔订单"
+- "找一下所有跟 email 相关的字段"
+- "看看 products 表里长什么样"
+
+## 安全设计
+
+- **默认只读** —— 查询操作不会修改任何数据
+- **写入需授权** —— 必须设置 `allow_writes=True` 和 `MCP_DATABASE_READ_ONLY=false`
+- **语句检测** —— 写入工具会拒绝 SELECT 语句（应该用 `query`）
+- **行数限制** —— 可配置最大返回行数，防止意外拉取全表
+
+## 开发
+
+```bash
+# 克隆并安装
+git clone https://github.com/Jansen003/mcp-database.git
+cd mcp-database
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 使用 Inspector 调试
+mcp dev src/mcp_database/server.py
+```
+
+## 项目结构
+
+```
+src/mcp_database/
+  __init__.py          # 版本信息
+  server.py            # MCP 服务器主入口（8 个工具）
+  config.py            # 配置加载（环境变量、URL 解析）
+  adapters/
+    base.py            # 适配器基类（DatabaseAdapter）
+    sqlite.py          # SQLite 适配器
+    postgres.py        # PostgreSQL 适配器
+    mysql.py           # MySQL 适配器
+tests/
+  test_sqlite_adapter.py  # SQLite 适配器测试（17 个用例）
+```
+
+## 许可证
+
+MIT — 详见 [LICENSE](LICENSE)。

mcp_database-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-database"
+version = "0.1.0"
+description = "MCP server for multi-database access — SQLite, PostgreSQL, MySQL. Query, inspect schema, and manage databases through Claude."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Mergewall Team"}
+]
+keywords = ["mcp", "database", "sqlite", "postgresql", "mysql", "claude", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+postgres = ["psycopg2-binary>=2.9.0"]
+mysql = ["pymysql>=1.1.0"]
+all = ["mcp-database[postgres,mysql]"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.4.0",
+]
+
+[project.scripts]
+mcp-database = "mcp_database.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_database"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"

mcp_database-0.1.0/src/mcp_database/__init__.py

@@ -0,0 +1,3 @@
+"""mcp-database — MCP server for multi-database access."""
+
+__version__ = "0.1.0"

mcp_database-0.1.0/src/mcp_database/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m mcp_database"""
+
+from mcp_database.server import main
+
+main()

mcp_database-0.1.0/src/mcp_database/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Database adapters for mcp-database."""
+
+from mcp_database.adapters.base import DatabaseAdapter
+from mcp_database.adapters.sqlite import SQLiteAdapter
+
+__all__ = ["DatabaseAdapter", "SQLiteAdapter"]

mcp_database-0.1.0/src/mcp_database/adapters/base.py

@@ -0,0 +1,108 @@
+"""Base adapter interface for database connections."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class QueryResult:
+    """Result of a SQL query."""
+
+    columns: list[str]
+    rows: list[list[Any]]
+    row_count: int
+    truncated: bool = False
+
+    def to_table(self, max_rows: int = 100) -> str:
+        """Format result as an aligned text table."""
+        if not self.columns:
+            return "No results."
+
+        rows = self.rows[:max_rows]
+        # Calculate column widths
+        widths = [len(c) for c in self.columns]
+        for row in rows:
+            for i, val in enumerate(row):
+                if i < len(widths):
+                    widths[i] = max(widths[i], len(str(val)))
+
+        # Header
+        header = " | ".join(c.ljust(widths[i]) for i, c in enumerate(self.columns))
+        separator = "-+-".join("-" * w for w in widths)
+        lines = [header, separator]
+
+        # Rows
+        for row in rows:
+            line = " | ".join(str(row[i]).ljust(widths[i]) if i < len(row) else "" for i in range(len(self.columns)))
+            lines.append(line)
+
+        result = "\n".join(lines)
+        if self.truncated:
+            result += f"\n... ({self.row_count} total rows, showing first {max_rows})"
+        return result
+
+
+@dataclass
+class TableInfo:
+    """Information about a database table."""
+
+    name: str
+    columns: list[dict[str, Any]]
+    row_count: int | None = None
+    create_sql: str | None = None
+
+
+class DatabaseAdapter(ABC):
+    """Abstract base class for database adapters."""
+
+    @abstractmethod
+    def connect(self) -> None:
+        """Establish connection to the database."""
+
+    @abstractmethod
+    def disconnect(self) -> None:
+        """Close the database connection."""
+
+    @abstractmethod
+    def test_connection(self) -> bool:
+        """Test if the connection is alive."""
+
+    @abstractmethod
+    def list_databases(self) -> list[str]:
+        """List available databases (if applicable)."""
+
+    @abstractmethod
+    def list_tables(self, database: str | None = None) -> list[str]:
+        """List all tables in the database."""
+
+    @abstractmethod
+    def get_table_info(self, table: str, database: str | None = None) -> TableInfo:
+        """Get detailed information about a table."""
+
+    @abstractmethod
+    def get_schema(self, database: str | None = None) -> str:
+        """Get the full database schema as formatted text."""
+
+    @abstractmethod
+    def execute_query(self, sql: str, database: str | None = None, max_rows: int = 100) -> QueryResult:
+        """Execute a read-only SQL query."""
+
+    def execute_write(self, sql: str, database: str | None = None) -> int:
+        """Execute a write SQL query (INSERT/UPDATE/DELETE). Returns affected rows.
+
+        Raises NotImplementedError if the adapter is read-only.
+        """
+        raise NotImplementedError("This adapter is read-only. Use execute_query() for SELECT statements.")
+
+    @property
+    @abstractmethod
+    def db_type(self) -> str:
+        """Return the database type name (e.g., 'sqlite', 'postgresql', 'mysql')."""
+
+    def _is_read_only_query(self, sql: str) -> bool:
+        """Check if a query is read-only (SELECT, SHOW, DESCRIBE, EXPLAIN)."""
+        normalized = sql.strip().upper()
+        # Allow SELECT, SHOW, DESCRIBE, EXPLAIN, WITH (CTE leading to SELECT)
+        read_only_prefixes = ("SELECT", "SHOW", "DESCRIBE", "DESC", "EXPLAIN", "WITH", "PRAGMA")
+        return any(normalized.startswith(prefix) for prefix in read_only_prefixes)