sleep1223/askdb-mcp

AskDB-MCP

基于 RBAC 的智能问数平台 —— 用自然语言查询数据库，通过 MCP 协议暴露数据源能力。

特性

• 自然语言查询 — LLM 驱动的 Text-to-SQL，支持多轮对话
• 多数据源 — PostgreSQL、MySQL、ClickHouse、Doris、StarRocks、Oracle、MSSQL、SQLite、DuckDB
• RBAC 权限控制 — 行级 / 字段级细粒度权限
• MCP 协议 — 标准 MCP 接口，支持 JWT / AppKey 双重鉴权，可直接对接 Claude Desktop 等 MCP 客户端
• 插件架构 — 事件驱动，内置 SQL 安全守卫插件
• 开箱即用 — 内置 SQLite 主库，无需额外数据库即可启动

快速开始

1. 创建配置文件

bash
mkdir -p askdb && cd askdb

cat > .env << 'EOF'
# 必须修改：JWT 密钥（至少 32 字符的随机字符串）
JWT_SECRET=your-random-secret-string-at-least-32-characters

# 可选：大模型配置
# LLM_CUSTOM_MODELS='[
#   {
#     "name": "default",
#     "provider": "openai",
#     "model": "gpt-4o-mini",
#     "api_key": "sk-your-api-key",
#     "api_base": "https://api.openai.com/v1",
#     "comment": "默认模型"
#   }
# ]'
# LLM_GLOBAL_MODEL=default

# Redis（REDIS_URL和REDIS_USE_FAKEREDIS二选一）
# REDIS_URL=redis://:password@your-redis-host:6379
REDIS_USE_FAKEREDIS=true

# 运行环境
APP_ENV=prod
EOF

2. 使用 Docker Compose 部署（推荐）

yaml
# docker-compose.yml
services:
  app:
    image: sleep1223/askdb-mcp:latest
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./data:/app/data
    env_file:
      - .env

bash
docker compose up -d

3. 使用 Docker Run 部署

bash
docker run -d \
  --name askdb-mcp \
  --restart unless-stopped \
  -p 8080:80 \
  -v askdb-data:/app/data \
  --env-file .env \
  sleep1223/askdb-mcp:latest

4. 访问服务

• Web 控制台：http://localhost:8080
• API 文档：http://localhost:8080/api/v1/docs
• MCP 端点：http://localhost:8080/mcp
• 健康检查：http://localhost:8080/api/v1/health

默认管理员账号：admin / admin123（首次登录后请立即修改密码）

MCP 客户端接入

在 Claude Desktop 或其他 MCP 客户端中添加配置：

json
{
  "mcpServers": {
    "askdb": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <your-jwt-token>"
      }
    }
  }
}

支持的 MCP 工具：

环境变量

必须配置

可选配置

数据持久化

容器内 /app/data 目录包含：

• main.db — 主数据库（用户、数据源配置、权限等）
• debug/ — 调试日志

务必挂载此目录，否则容器重启后数据丢失。

技术栈

• 后端：Python 3.12 · FastAPI · Tortoise ORM · FastMCP · Granian
• 前端：Vue 3 · TypeScript · PrimeVue 4 · Tailwind CSS 4
• 运行时：Nginx · Supervisor

许可证

MIT