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:

| Parameter | Required | Type | Description | |-----------|----------|------|-------------| | host | Yes | string | Database server address | | port | Yes | integer | Database server port number | | user | Yes | string | Database username | | password | Yes | string | Database user password | | database | Yes | string | Database name to connect to | | role | Yes | string | User role, such as "readonly" for read-only permissions | | pool_size | Yes | integer | Connection pool size | | max_overflow | Yes | integer | Maximum overflow connections in connection pool | | pool_recycle | Yes | integer | Connection pool recycle time (seconds) | | pool_timeout | Yes | integer | Connection pool timeout time (seconds) | | type | Yes | string | Database type, such as "mysql", "postgresql", "oracle", "mssqlserver" |

• Additional Parameters for Specific Databases

| Parameter | Database Type | Required | Type | Description | |-----------|---------------|----------|------|-------------| | schema | PostgreSQL, SQL Server | No | string | Database schema | | service_name | Oracle | No | string | Oracle 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": [