AI导哈

数据库语义层服务

db-mcp是一个开源MCP服务器，连接Claude Desktop到您的数据库，提供自学习的语义层，使查询更智能。

  • by apelogic-ai
  • Python
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 apelogic-ai/db-mcp

使用说明

db-mcp

您的团队正在将公司数据复制粘贴到Claude中。给他们一个安全的方法。

db-mcp是一个开源的mcp服务器，它将Claude Desktop连接到您的数据库，并具有一个自我改进的语义层，每个查询都会变得更加智能。

不需要基础设施。在当地运行。数据永远不会离开你的网络。

安装

curl -fsSL https://download.apelogic.ai/db-mcp/install.sh | sh

为什么选择db-mcp？

  • 问克劳德，得到答案 --别再等报告了。使用自然语言查询数据，无需SQL、复制粘贴模式或上下文设置
  • 自改进语义层 --自动生成模式的描述，然后从每个查询中学习以提高准确性
  • 在您的桌面上运行 --没有云基础设施，没有数据离开您的网络。使用您现有的数据库凭据和访问控制
  • Git风格的协作 --数据团队审查和批准语义层改进。你保持控制，用户得到准确的答案
  • 开源和可审计 --麻省理工学院授权，完全透明，无供应商锁定

db-mcp是为谁服务的？

角色 利益
业务团队 向Claude询问有关您的数据的问题，并立即获得准确的答案——不需要SQL
数据团队 将您的仓库转变为一个支持代理的平台，该平台具有一个自我构建的语义层
IT与安全 通过完整的交互历史、只读执行和成本保护来管理人工智能数据访问

运作原理

从安装到洞察，分为四个步骤：

  1. 安装 --将db-mcp下载到您的笔记本电脑。无需基础设施，几分钟内即可在本地运行
  2. 连接 --使用现有凭据添加数据源。您的安全态势保持不变
  3. 查询 --在您的连接数据中向Claude提问。每个查询在执行前都经过验证
  4. 改进 --语义层从用法中学习。使用git风格的工作流审查和批准改进

快速开始

# Configure your database and Claude Desktop
db-mcp init

# Check configuration
db-mcp status

支持的代理

克劳德桌面版

默认设置适用于Claude Desktop。按照上面的快速入门说明进行操作。

开爪

db-mcp与 开爪 通过mcporter：

# Install mcporter (MCP bridge for OpenClaw)
npm i -g mcporter

# Configure db-mcp for OpenClaw
db-mcp init

或手动添加到 ~/.openclaw/workspace/config/mcporter.json:

{
  "mcpServers": {
    "db-mcp": {
      "command": "db-mcp",
      "args": ["start"]
    }
  }
}

支持的数据库

  • PostgreSQL
  • ClickHouse
  • 特里诺
  • MySQL
  • SQL Server

安全与治理

  • 在本地运行 --数据保留在您的计算机上，从不通过外部服务器路由
  • 默认情况下为只读 --查询验证和成本保护可防止意外修改数据
  • 使用现有RBAC --使用您的数据库凭据连接并尊重您的访问控制
  • 完整的审计追踪 --合规性和调试的完整交互历史记录
  • 开源 --完全可审计，麻省理工学院许可

命令

设置和配置

命令 描述
db-mcp init [NAME] 交互式设置向导-配置数据库和Claude Desktop
db-mcp status 显示当前配置状态
db-mcp config 在编辑器中打开配置文件

连接管理

命令 描述
db-mcp list 列出所有已配置的连接
db-mcp use NAME 切换到其他连接
db-mcp edit [NAME] 编辑连接凭据（.env文件）
db-mcp rename OLD NEW 重命名连接
db-mcp remove NAME 删除连接
db-mcp all COMMAND 对所有连接运行命令

服务器和诊断

命令 描述
db-mcp start 启动MCP服务器（Claude Desktop的stdio模式）
db-mcp console 启动本地跟踪控制台（查看MCP服务器活动）
db-mcp traces 管理跟踪捕获以进行诊断和学习

Git同步（团队协作）

命令 描述
db-mcp git-init [NAME] 为现有连接启用git同步
db-mcp sync [NAME] 使用git remote同步连接更改
db-mcp pull [NAME] 从git remote获取连接更新

迁移

命令 描述
db-mcp migrate 从传统存储格式迁移到新的连接结构

配置

连接数据存储在 ~/.db-mcp/:

~/.db-mcp/
├── config.yaml                      # Global config, active connection
└── connections/{name}/
    ├── .env                         # Database credentials (gitignored)
    ├── state.yaml                   # Onboarding state
    ├── schema/
    │   └── descriptions.yaml        # Table/column descriptions
    ├── domain/
    │   └── model.md                 # Domain model documentation
    ├── training/
    │   ├── examples.yaml            # Query examples (NL → SQL mappings)
    │   └── instructions.yaml        # Custom SQL generation rules
    └── .git/                        # Optional git sync for team sharing

配置工件

文件 目的
config.yaml 全局设置：活动连接、首选项
.env 数据库URL和凭据（从未提交到git）
state.yaml 入职进度（发现→ 审查→ 域构建→ 完成）
schema/descriptions.yaml 表和列的可读描述
domain/model.md LLM的业务领域文档
training/examples.yaml 用于指导SQL生成的已知良好查询示例
training/instructions.yaml SQL生成的自定义规则和约束

环境变量

变量 描述
DATABASE_URL 连接字符串（必填）
CONNECTION_NAME 覆盖活动连接
CONNECTION_PATH 覆盖连接目录路径
LOG_LEVEL 记录详细程度（默认值：INFO）

发展

# Clone
git clone https://github.com/apelogic-ai/db-mcp.git
cd db-mcp

# Install dependencies
uv sync

# Run locally
cd packages/core
uv run db-mcp --help

# Lint
cd packages/core && uv run ruff check . --fix
cd packages/ui && bun run lint

# Build binary
cd packages/core
uv run python scripts/build.py

测试

三层共93次测试：

# Python unit tests (49 tests)
cd packages/core
uv run pytest tests/ -v

# UI unit tests (20 tests)
cd packages/ui
bun run test

# UI E2E tests (24 tests)
cd packages/ui
bunx playwright test

所有测试在每次推送和PR时都通过GitHub Actions在CI中运行。请参阅 docs/testing.md 查看完整的测试指南。

工具覆盖检查

验证代码库中实现的MCP工具100%在运行时由MCP服务器公开：

# Run the tool coverage audit (default SQL mode)
python scripts/tool_coverage_audit.py

# Test different configuration modes
python scripts/tool_coverage_audit.py --config api
python scripts/tool_coverage_audit.py --config shell
python scripts/tool_coverage_audit.py --config metabase

# Verbose output with all tool names
python scripts/tool_coverage_audit.py --verbose

# JSON output for CI integration
python scripts/tool_coverage_audit.py --json

审核成功时返回退出代码0（100%覆盖率），失败时返回1。

项目结构

db-mcp/
├── packages/
│   ├── core/                # Main application (db-mcp)
│   ├── models/              # Shared Pydantic models (db-mcp-models)
│   └── ui/                  # Next.js control plane UI
├── docs/                    # Design documents
├── scripts/                 # Installation scripts
└── .github/workflows/       # CI/CD

路线图

看 docs/ 关于规划特征的设计文件：

  • 度量层 -语义度量定义（DAU、收入等）
  • 桌面应用程序 -带有可视化查询构建器的电子GUI
  • 知识提取 -自动从查询跟踪中学习
  • 数据网关 -统一访问多个数据源

资源

许可证

麻省理工学院

相关 MCP