convez.ai
MCP ServerDados & AnalyticsAvançado
wenb1n-dev

SmartDB MCP

wenb1n-dev/SmartDB_MCP

Gateway universal para BD com otimização SQL e diagnósticos inteligentes

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP universal que conecta a múltiplos bancos de dados (MySQL, PostgreSQL, SQL Server, MariaDB, DM8, Oracle) com suporte a autenticação OAuth 2.0, verificação de saúde, otimização de SQL e detecção de índices. Oferece ferramentas avançadas para execução segura de queries, análise de performance e diagnóstico de problemas em BD.

Instalação

$npx convez-ai wenb1n-dev/SmartDB_MCP

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
78
Forks
21
Acompanhando
1
Saúde
42%
Último commit
há 3 semanas
Versão
v1.0.0
Issues abertas
12
Contribuidores
4

Casos de uso

  • Conectar Claude a bancos de dados corporativos para análise de dados
  • Otimizar queries SQL automaticamente e diagnosticar problemas de performance
  • Gerenciar múltiplos bancos de dados (MySQL, PostgreSQL, Oracle, SQL Server) de forma integrada
  • Auditar saúde de bancos de dados e detectar locks e transações travadas

Veredito

SmartDB é uma solução robusta e enterprise-ready para conectar Claude a infraestruturas complexas de bancos de dados. Suporte multi-BD, autenticação segura e ferramentas de diagnóstico o tornam ideal para ambientes corporativos, embora exija conhecimento técnico sólido para configuração.

README

A tradução para o português deste README ainda está na fila.

简体中文 English MseeP.ai Security Assessment Badge

SmartDB

SmartDB is a universal database gateway that implements the Model Context Protocol (MCP) server interface. This gateway allows MCP-compatible clients to connect and explore different databases.

Compared to similar products, SmartDB not only provides basic database connection and exploration capabilities but also adds advanced features such as OAuth 2.0 authentication , health checks, SQL optimization, and index health detection, making database management and maintenance more secure and intelligent.

Currently Supported Databases

DatabaseSupportDescription
MySQL√Supports MySQL 5.6+, MariaDB 10+
PostgreSQL√Supports PostgreSQL 9.6+, YMatrix
Oracle√Oracle 12+
SQL Server√Microsoft SQL Server 2012+
Dameng√Dameng 8.0+

Tool List

Tool NameDescription
execute_sqlSQL execution tool that can execute ["SELECT", "SHOW", "DESCRIBE", "EXPLAIN", "INSERT", "UPDATE", "DELETE", "CREATE", "ALTER", "DROP", "TRUNCATE"] commands based on permission configuration
get_db_healthAnalyzes database health status (connection status, transaction status, running status, lock detection) and outputs professional diagnostic reports and solutions
get_table_descSearches for table structures in the database based on table names, supports multi-table queries
get_table_indexSearches for table indexes in the database based on table names, supports multi-table queries
get_table_nameDatabase table name query tool. Used to query all table names in the database or search for corresponding table names based on Chinese table names or table descriptions
get_db_versionDatabase version query tool
sql_creatorSQL query generation tool that generates corresponding SQL query statements based on different database types
sql_optimizeA professional SQL performance optimization tool that provides expert optimization suggestions based on execution plans, table structure information, table data volume, and table indexes.

Usage

Environment Configuration File Description

# Database configuration file path
DATABASE_CONFIG_FILE=/Volumes/SmartDB/src/config/database_config.json

#========OAuth2========
# OAuth2 client ID
CLIENT_ID=smart_db_client_id
# OAuth2 client secret
CLIENT_SECRET=smart_db_client_secret
# Access token expiration time (minutes)
ACCESS_TOKEN_EXPIRE_MINUTES=30
# Refresh token expiration time (days)
REFRESH_TOKEN_EXPIRE_DAYS=30
# Token encryption key
TOKEN_SECRET_KEY=smart_db_token_secret
# Username
OAUTH_USER_NAME=admin
# Password
OAUTH_USER_PASSWORD=wenb1n

Note: If you adjust the client ID and key in the oauth configuration, please also modify the corresponding configuration in the static/config file in the previous code

Database Connection Configuration Description

{
  "default": {
    "host": "192.168.xxx.xxx",
    "port": 3306,
    "user": "root",
    "password": "root",
    "database": "a_llm",
    "role": "readonly",
    "pool_size": 10,
    "max_overflow": 20,
    "pool_recycle": 3600,
    "pool_timeout": 30,
    "type": "mysql"
  },
  "postgresql": {
    "host": "192.168.xxx.xxx",
    "port": 5432,
    "user": "postgres",
    "password": "123456",
    "database": "postgres",
    "schema": "public",
    "role": "readonly",
    "pool_size": 5,
    "max_overflow": 10,
    "pool_recycle": 3600,
    "pool_timeout": 30,
    "type": "postgresql"
  },
  "oracle": {
    "host": "192.168.xxx.xxx",
    "port": 1521,
    "user": "U_ORACLE",
    "password": "123456",
    "database": "123456",
    "service_name": "ORCL",
    "role": "readonly",
    "pool_size": 5,
    "max_overflow": 10,
    "pool_recycle": 3600,
    "pool_timeout": 30,
    "type": "oracle"
  },
  "mssql": {
    "host": "192.168.xxx.xxx",
    "port": 1433,
    "user": "test",
    "password": "123456",
    "database": "TEST",
    "schema": "dbo",
    "role": "readonly",
    "pool_size": 5,
    "max_overflow": 10,
    "pool_recycle": 3600,
    "pool_timeout": 30,
    "type": "mssqlserver"
  }
}
  • Database Connection Parameter Description

The following table details the meaning and usage of each parameter in the database connection configuration file:

ParameterRequiredTypeDescription
hostYesstringDatabase server address
portYesintegerDatabase server port number
userYesstringDatabase username
passwordYesstringDatabase user password
databaseYesstringDatabase name to connect to
roleYesstringUser role, such as "readonly" for read-only permissions
pool_sizeYesintegerConnection pool size
max_overflowYesintegerMaximum overflow connections in connection pool
pool_recycleYesintegerConnection pool recycle time (seconds)
pool_timeoutYesintegerConnection pool timeout time (seconds)
typeYesstringDatabase type, such as "mysql", "postgresql", "oracle", "mssqlserver"
  • Additional Parameters for Specific Databases
ParameterDatabase TypeRequiredTypeDescription
schemaPostgreSQL, SQL ServerNostringDatabase schema
service_nameOracleNostringOracle service name
  • role permission control configuration items and corresponding database permissions: readonly (readonly), read/write (writer), administrator (admin)
    "readonly": ["SELECT", "SHOW", "DESCRIBE", "EXPLAIN"],  # readonly permission
    "writer": ["SELECT", "SHOW", "DESCRIBE", "EXPLAIN", "INSERT", "UPDATE", "DELETE"],  # read/write permission
    "admin": ["SELECT", "SHOW", "DESCRIBE", "EXPLAIN", "INSERT", "UPDATE", "DELETE", 
             "CREATE", "ALTER", "DROP", "TRUNCATE"]  # administrator permission
  • Note

"default" is the default database connection configuration and must be configured. Other database configurations should be added as needed.

pip installation and configuration

pip install SmartDB-MCP

Parameter explanation
--mode: transmission mode ("stdio", "sse", "streamablehttp")
--envfile path of the environment variable file
--oauth enable oauth authentication (currently only supported in "streamablehttp" mode)

Start command:
 smartdb --envfile=/Volumes/config/.env --oauth=true


Docker Startup

Quick Start

1. Build and Start Service

# Start service using docker-compose
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f smartdb

2. Manual Image Building

# Build image
docker build -t smartdb-mcp:latest .

# Run container
docker run -d \
  --name smartdb-mcp-server \
  -p 3000:3000 \
  -e DATABASE_CONFIG_FILE=/app/src/config/database_config.json \
  -e CLIENT_ID=smart_db_client_id \
  -e CLIENT_SECRET=smart_db_client_secret \
  -e TOKEN_SECRET_KEY=your_secret_key \
  -v $(pwd)/src/config:/app/src/config:ro \
  -v $(pwd)/logs:/app/logs \
  smartdb-mcp:latest

Code Startup

Local Development Streamable Http Mode

  • Start service using uv

Add the following content to your MCP client tools, such as cursor, cline, etc.

MCP JSON as follows:

{
  "mcpServers": {
    "smartdb": {
      "name": "smartdb",
      "type": "streamableHttp",
      "description": "",
      "isActive": true,
      "url": "http://localhost:3000/mcp/"
    }
  }
}

Start command:

# Download dependencies
uv sync

# Start
uv run -m core.server

# Custom env file location
uv run -m core.server --envfile /path/to/.env

Local Development SSE Mode

  • Start service using uv

Add the following content to your MCP client tools, such as cursor, cline, etc.

MCP JSON as follows:

{
  "mcpServers": {
    "smartdb": {
      "name": "smartdb",
      "description": "",
      "isActive": true,
      "url": "http://localhost:3000/sse"
    }
  }
}

Start command:

# Download dependencies
uv sync

# Start
uv run -m core.server --mode sse

# Custom env file location
uv run -m core.server --mode sse --envfile /path/to/.env

Local Development STDIO Mode

Add the following content to your MCP client tools, such as cursor, cline, etc.

MCP JSON as follows:

{
  "mcpServers": {
      "smartdb": {
          "name": "smartdb",
          "type": "stdio",
          "isActive": false,
          "registryUrl": "",
          "command": "uv",
          "args": [
            "--directory",
            "/Volumes/python/SmartDB/",
            "run",
            "-m",
            "core.server",
            "--mode",
            "stdio"
          ],
          "env": {
            "DATABASE_CONFIG_FILE": "/Volumes/database_config.json"
          }
      }
    }
  }
}

OAuth 2.0 Authentication Support

  1. Start authentication service. By default, it uses the built-in OAuth 2.0 password mode authentication. You can modify your own authentication service address in the env file.
uv run -m core.server --oauth=true
  1. Access the authentication service at http://localhost:3000/login. Default account and password are configured in the env file.

  2. Copy the token and add it to the request header, for example:

{
  "mcpServers": {
    "smartdb": {
      "name": "smartdb",
      "type": "streamableHttp",
      "description": "",
      "isActive": true,
      "url": "http://localhost:3000/mcp/",
      "headers": {
        "authorization": "bearer TOKEN_VALUE"
      }
    }
  }
}

Usage Examples

  1. Query the table data of the default connection pool

  2. Query the table data of the others connection pool

  3. Query data from tables in other connection pools and other databases

  4. Query database health status

  5. Sql Optimize

Ver o original no GitHub

Bom para

Relacionados