使用说明

数据库架构MCP服务器

用于从多种数据库类型中提取数据库模式信息的模型上下文协议（MCP）服务器。旨在为LLM提供全面的数据库结构信息，以更好地生成SQL、数据分析和理解数据库。

特性

多数据库支持：连接到14种以上的数据库类型
- 关系型：MySQL、PostgreSQL、OpenGauss、SQLite、Oracle、ClickHouse
- NoSQL：MongoDB、Redis、Memcached
- 消息队列：Kafka、RabbitMQ
- 搜索/分析：Elasticsearch
- 键值存储：etcd
- 矢量数据库：Milvus
全面的模式提取:
- 表、列、数据类型
- 主键、索引、唯一约束
- 外键关系
- 视图和存储过程
- MongoDB字段类型推断（基于采样）
- Redis密钥模式分析
- Kafka主题配置
LLM优化输出：所有模式信息的格式都是干净、结构化的Markdown
可扩展架构：易于添加对新数据库类型（Pulsar、etcd、Cassandra等）的支持
环境变量支持：通过以下方式进行安全密码管理 ${VAR_NAME} 语法

安装

npm install
npm run build

配置

1.创建配置文件

复制示例配置并对其进行自定义：

cp config.example.json config.json

2.配置数据库

编辑 config.json 要添加数据库连接，请执行以下操作：

{
  "databases": {
    "my_mysql": {
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "database": "myapp",
      "user": "root",
      "password": "${MYSQL_PASSWORD}"
    },
    "my_postgres": {
      "type": "postgresql",
      "connectionString": "postgresql://user:pass@localhost:5432/mydb"
    },
    "my_mongodb": {
      "type": "mongodb",
      "uri": "mongodb://localhost:27017",
      "database": "myapp",
      "sampleSize": 1000
    }
  }
}

3.设置环境变量

对于敏感凭据，请使用环境变量：

export MYSQL_PASSWORD="your_password"
export POSTGRES_PASSWORD="your_password"
export REDIS_PASSWORD="your_password"

用法

此工具提供了两种访问数据库模式信息的方法：

CLI工具 -用于快速提取模式的命令行界面
MCP服务器 -用于与Claude Desktop和其他MCP客户端集成的模型上下文协议服务器

使用CLI工具

构建并链接包后，您可以使用 db-schema 命令：

# Install and link the package
npm install
npm run build
npm link

# Get complete database schema
db-schema --config config.json --database my_mysql

# List all tables
db-schema --config config.json --database my_mysql --list-tables

# Get details for a specific table
db-schema --config config.json --database my_mysql --table users

# Export schema to a file
db-schema --config config.json --database my_mysql --output schema.md

# Use environment variable for config path
export DB_SCHEMA_CONFIG=config.json
db-schema --database my_mysql

CLI选项：

-c, --config <path> -配置文件的路径（除非设置了DB_SCHEMA_CONFIG，否则是必需的）
-d, --database <name> -配置中的数据库名称（必填）
-l, --list-tables -列出所有表格/集合/主题
-t, --table <name> -获取特定表格的详细信息
-o, --output <path> -输出文件路径（默认：stdout）

运行MCP服务器

npm start

或者设置自定义配置路径：

DB_SCHEMA_CONFIG=/path/to/config.json npm start

可用的MCP工具

1. `get_database_schema`

获取Markdown格式的完整数据库模式。

参数：

databaseName （string）：config.json中的数据库名称

例子：

{
  "databaseName": "my_mysql"
}

2. `list_tables`

列出数据库中的所有表/集合/主题。

参数：

databaseName （string）：config.json中的数据库名称

3. `get_table_details`

获取特定表格的详细信息。

参数：

databaseName （string）：config.json中的数据库名称
tableName （string）：表的名称

数据库特定配置

MySQL

{
  "type": "mysql",
  "host": "localhost",
  "port": 3306,
  "database": "mydb",
  "user": "root",
  "password": "password"
}

PostgreSQL

{
  "type": "postgresql",
  "host": "localhost",
  "port": 5432,
  "database": "mydb",
  "user": "postgres",
  "password": "password",
  "schema": "public"
}

或者使用连接字符串：

{
  "type": "postgresql",
  "connectionString": "postgresql://user:pass@localhost:5432/mydb"
}

OpenGauss 的

OpenGauss与PostgreSQL协议兼容：

{
  "type": "opengauss",
  "host": "localhost",
  "port": 5433,
  "database": "mydb",
  "user": "gaussdb",
  "password": "password",
  "schema": "public"
}

SQLite

{
  "type": "sqlite",
  "database": "/path/to/database.db"
}

甲骨文

{
  "type": "oracle",
  "host": "localhost",
  "port": 1521,
  "user": "system",
  "password": "password",
  "serviceName": "ORCL"
}

注：需要在您的系统上安装Oracle Instant Client。

MongoDB

{
  "type": "mongodb",
  "uri": "mongodb://localhost:27017",
  "database": "mydb",
  "sampleSize": 1000
}

现场推断： MongoDB连接器示例最多 sampleSize 文档（默认值：1000），用于推断字段类型和出现率。

瑞迪斯

{
  "type": "redis",
  "host": "localhost",
  "port": 6379,
  "password": "password",
  "db": 0,
  "maxKeys": 1000,
  "keyPattern": "*"
}

关键模式分析： 扫描至 maxKeys 密钥匹配 keyPattern 以识别命名模式和数据类型。

内存缓存

{
  "type": "memcached",
  "servers": ["localhost:11211"]
}

备注：Memcached不支持密钥枚举。连接器仅提供缓存统计信息。

卡夫卡

{
  "type": "kafka",
  "brokers": ["localhost:9092"],
  "clientId": "database-schema-mcp"
}

RabbitMQ 的

{
  "type": "rabbitmq",
  "host": "localhost",
  "port": 5672,
  "user": "guest",
  "password": "password",
  "vhost": "/"
}

备注：要求启用RabbitMQ管理API以获得完整的队列/交换列表。

弹性搜索

{
  "type": "elasticsearch",
  "node": "http://localhost:9200"
}

通过身份验证：

{
  "type": "elasticsearch",
  "nodes": ["http://localhost:9200"],
  "auth": {
    "username": "elastic",
    "password": "password"
  }
}

弹性云：

{
  "type": "elasticsearch",
  "cloudId": "your-cloud-id",
  "auth": {
    "apiKey": "your-api-key"
  }
}

etcd

{
  "type": "etcd",
  "hosts": ["localhost:2379"],
  "prefix": "/",
  "maxKeysToScan": 1000
}

通过身份验证：

{
  "type": "etcd",
  "hosts": ["localhost:2379"],
  "username": "root",
  "password": "password"
}

ClickHouse

{
  "type": "clickhouse",
  "host": "localhost",
  "port": 8123,
  "database": "default",
  "username": "default",
  "password": "password"
}

米尔维斯

{
  "type": "milvus",
  "address": "localhost:19530"
}

通过身份验证：

{
  "type": "milvus",
  "address": "localhost:19530",
  "username": "root",
  "password": "password",
  "secure": false
}

添加新数据库类型

该架构的设计便于扩展。要添加新的数据库类型，请执行以下操作：

创建连接器 在 src/connectors/:

// src/connectors/etcd.ts
import { DatabaseConnector } from './base.js';
import { registerConnector } from './factory.js';

export class EtcdConnector extends DatabaseConnector {
  async connect() { /* implementation */ }
  async disconnect() { /* implementation */ }
  async getSchema() { /* implementation */ }
  // ... implement other required methods
}

registerConnector('etcd', EtcdConnector);

导入连接器 在 src/index.ts:

import './connectors/etcd.js';

重建和使用:

npm run build

建筑

database-schema-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types/schema.ts       # Type definitions
│   ├── config/loader.ts      # Config file loader
│   ├── connectors/
│   │   ├── base.ts           # Abstract base class
│   │   ├── factory.ts        # Connector registry & factory
│   │   ├── mysql.ts          # MySQL implementation
│   │   ├── postgresql.ts     # PostgreSQL implementation
│   │   ├── sqlite.ts         # SQLite implementation
│   │   ├── oracle.ts         # Oracle implementation
│   │   ├── mongodb.ts        # MongoDB implementation
│   │   ├── redis.ts          # Redis implementation
│   │   └── kafka.ts          # Kafka implementation
│   ├── schema/formatter.ts   # Markdown formatter
│   └── tools/schema-tools.ts # MCP tool handlers
└── config.json               # Your database configuration

发展

使用Makefile（推荐）

该项目包括一个用于常见开发任务的Makefile：

# View all available commands
make help

# Install dependencies
make install

# Build the project
make build

# Run in watch mode (auto-rebuild on changes)
make dev

# Quick start (install + build + start)
make start

直接使用npm

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode (auto-rebuild on changes)
npm run dev

测试

使用Makefile进行快速测试

# Run all tests (unit + integration)
make test

# Run only unit tests (fast, no databases required)
make test-unit

# Run integration tests with test databases
make test-integration

# Run tests in watch mode
make test-watch

# Run tests with coverage report
make test-coverage

管理测试数据库

该项目使用Docker Compose提供测试数据库：

# Start all test databases (MySQL, PostgreSQL, MongoDB, Redis, Kafka)
make test-db-up

# Stop and remove test databases
make test-db-down

# View test database logs
make test-db-logs

# Check test database status
make test-db-status

直接使用npm

# Run all tests
npm test

# Run only unit tests
npm run test:unit

# Run only integration tests (requires databases)
npm run test:integration

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

测试覆盖率

该项目包括综合测试：

单元测试：配置加载器、连接器工厂、模式格式化器
集成测试：所有具有真实数据库操作的数据库连接器
- MySQL连接器
- PostgreSQL连接器
- SQLite连接器
- MongoDB连接器
- Redis连接器
- Kafka连接器

看测试.md 获取详细的测试文档。

安全考虑

永不承诺 config.json 持有真实证件
对敏感数据使用环境变量
仅授予必要的数据库权限（建议只读）
对于生产使用，考虑加密配置文件

故障排除

Oracle连接问题

确保已安装Oracle Instant Client：

从Oracle网站下载
集 LD_LIBRARY_PATH （Linux）或 PATH （Windows）到即时客户端目录

MongoDB采样性能

对于非常大的收藏，减少 sampleSize 在配置中提高性能：

{
  "sampleSize": 100
}

Redis密钥扫描

如果Redis有数百万个密钥，请限制扫描 maxKeys 并使用特定的模式：

{
  "maxKeys": 500,
  "keyPattern": "user:*"
}

许可证

麻省理工学院

贡献

欢迎投稿！要添加对其他数据库的支持，请执行以下操作：

分叉存储库
按照现有图案创建新连接器
添加测试和文档
提交拉取请求

计划数据库支持

Pulsar（消息队列）
etcd（键值存储）
Cassandra（宽栏商店）
ElasticSearch（搜索引擎）
ClickHouse（OLAP数据库）
TiDB（分布式SQL）

使用说明

数据库架构MCP服务器

特性

安装

配置

1.创建配置文件

2.配置数据库

3.设置环境变量

用法

使用CLI工具

运行MCP服务器

可用的MCP工具

1. get_database_schema

2. list_tables

3. get_table_details

数据库特定配置

MySQL

PostgreSQL

OpenGauss 的

SQLite

甲骨文

MongoDB

瑞迪斯

内存缓存

卡夫卡

RabbitMQ 的

弹性搜索

etcd

ClickHouse

米尔维斯

添加新数据库类型

建筑

发展

使用Makefile（推荐）

直接使用npm

测试

使用Makefile进行快速测试

管理测试数据库

直接使用npm

测试覆盖率

安全考虑

故障排除

Oracle连接问题

MongoDB采样性能

Redis密钥扫描

许可证

贡献

计划数据库支持

相关 MCP

DBHub 数据库MCP服务器

高性能文本搜索内存系统

网页内容解析器

百度搜索MCP服务器

数据库连接服务器

AI认知检查工具

1. `get_database_schema`

2. `list_tables`

3. `get_table_details`