AI导哈

多数据库查询服务器

MCP数据库服务器提供多数据库查询执行能力，支持SQLite、PostgreSQL和MySQL数据库，并内置Web UI管理数据库连接。

  • by ahmetbarut
  • TypeScript
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 ahmetbarut/mcp-database-server

使用说明

MCP数据库服务器

一种模型上下文协议（MCP）服务器，提供多数据库查询执行功能，支持SQLite、PostgreSQL和MySQL数据库。包括用于管理数据库连接的内置Web UI。

NPM包

在NPM上可用： @ahmetbarut/mcp-database-server

# Use with npx (no installation required)
npx @ahmetbarut/mcp-database-server

# Or install globally
npm install -g @ahmetbarut/mcp-database-server

特性

  • 多数据库支持：具有真实连接的SQLite、PostgreSQL和MySQL
  • Web 界面：用于管理数据库连接的内置浏览器界面
  • SQLite配置存储：所有连接配置都保存在本地 ~/.mcp-database-server/connections.db
  • MCP协议合规性：完整的JSON-RPC实现，并提供完整的工具支持
  • 智能自动检测：自动为查询选择单个活动连接
  • 连接恢复：使用详细的错误报告重试失败的连接
  • 安全第一：参数化查询、SQL注入保护、审计日志记录
  • SSL支持：每个连接可配置SSL
  • 类型安全：带Zod验证的完整TypeScript实现
  • 兼容Node.js v23：适用于最新的Node.js版本

快速开始

npx @ahmetbarut/mcp-database-server

服务器启动，Web UI打开 http://localhost:3693。从浏览器添加数据库连接。

Web 界面

内置的Web UI为管理数据库连接提供了一个可视化界面：

  • 添加/编辑/删除 数据库连接（SQLite、PostgreSQL、MySQL）
  • 测试连接 保存之前
  • SSL切换 用于网络数据库
  • 持久存储 --连接在服务器重启后仍然存在

访问它在 http://localhost:3693 当服务器正在运行时。

环境变量

变量 默认值 描述
WEB_UI_PORT 3693 Web UI端口
WEB_UI_ENABLED true 启用/禁用Web UI
LOG_LEVEL info 日志记录级别(debug, info, warn, error)

MCP客户端配置

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@ahmetbarut/mcp-database-server"]
    }
  }
}

光标IDE

增添 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@ahmetbarut/mcp-database-server"]
    }
  }
}

自定义端口

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@ahmetbarut/mcp-database-server"],
      "env": {
        "WEB_UI_PORT": "4000"
      }
    }
  }
}

启动后，在浏览器中打开Web UI以添加数据库连接。

MCP工具

execute_query

使用参数化查询支持在数据库连接上执行SQL查询。

{
  "connection_name": "my-postgres",
  "query": "SELECT * FROM users WHERE status = $1",
  "parameters": ["active"]
}

list_databases

列出特定连接或所有已配置连接中的数据库。当只有一个连接处于活动状态时，支持智能自动检测。

{
  "connection_name": "my-postgres"
}

list_connections

列出所有数据库连接的状态和详细信息。

{
  "include_credentials": false
}

retry_failed_connections

重试失败的数据库连接。

{
  "connection_name": "my-postgres"
}

连接配置

所有数据库连接都通过 Web 界面 并存储在本地SQLite数据库中 ~/.mcp-database-server/connections.db.

支持的数据库类型

SQLite

  • 数据库文件的路径

PostgreSQL

  • 主机、端口、数据库、用户名、密码
  • SSL支持（可选）

MySQL

  • 主机、端口、数据库、用户名、密码
  • SSL支持（可选）

连接设置

设置 默认值 说明
maxConnections 10 最大连接池大小
timeout 30000 连接超时（毫秒）
ssl false 为连接启用SSL

发展

# Clone the repository
git clone https://github.com/ahmetbarut/mcp-database-server.git
cd mcp-database-server

# Install dependencies
npm install

# Development mode (hot-reload)
npm run dev

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Type check
npm run type-check

项目结构

mcp-database-server/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── server/
│   │   └── mcp-server.ts     # MCP server, tool handlers
│   ├── database/
│   │   ├── base.ts           # Abstract base driver
│   │   ├── factory.ts        # Driver factory & connection manager
│   │   └── drivers/          # SQLite, PostgreSQL, MySQL drivers
│   ├── config/
│   │   ├── settings.ts       # Config manager (loads from SQLite store)
│   │   └── config-store.ts   # SQLite-backed connection storage
│   ├── web/
│   │   ├── web-server.ts     # HTTP server for Web UI
│   │   ├── routes.ts         # REST API endpoints
│   │   └── ui.ts             # Embedded HTML/CSS/JS interface
│   ├── types/                # TypeScript types & Zod schemas
│   └── utils/                # Logger, exceptions, helpers
├── tests/unit/               # Jest test suites
└── dist/                     # Compiled output

建筑

npx @ahmetbarut/mcp-database-server
    │
    ├── MCPDatabaseServer
    │   ├── MCP stdio transport (JSON-RPC)
    │   ├── DatabaseConnectionManager
    │   └── WebUIServer (http://localhost:3693)
    │
    └── ConnectionConfigStore (~/.mcp-database-server/connections.db)
        └── SQLite database with connection configs
  1. 配置存储 从本地SQLite数据库加载已保存的连接
  2. 连接管理器 为每个配置初始化数据库驱动程序
  3. MCP服务器 通过stdio上的JSON-RPC公开工具
  4. Web 界面 通过REST API为连接提供基于浏览器的CRUD

安全

  • 参数化查询 --防止SQL注入
  • 凭证屏蔽 --密码隐藏在 list_connections 输出
  • 审核日志记录 --通过Winston记录的所有操作
  • 输入验证 --所有配置的Zod模式

测试

Test Suites: 2 passed, 2 total
Tests:       23 passed, 23 total

npm test               # Run all tests
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report

故障排除

Web UI不可访问

  • 检查端口3693是否已在使用中
  • 尝试其他端口： WEB_UI_PORT=4000

连接失败

  • 保存前使用Web UI中的“测试连接”按钮
  • 验证数据库服务器是否正在运行且可访问
  • 检查凭据和网络连接
  • 对于PostgreSQL：如果服务器不支持SSL，请禁用SSL

MCP客户端无法连接

  • 确保 npx @ahmetbarut/mcp-database-server 运行无错误
  • 配置更改后重新启动MCP客户端
  • 检查MCP客户端日志以了解错误详细信息

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

  1. 遵循TypeScript编码标准
  2. 添加新功能的测试
  3. 更新API变更文档
  4. 遵循安全准则

支持

对于问题和疑问，请使用 GitHub问题跟踪器.

相关 MCP