Universal DB MCP

# LM Studio 集成指南 本指南展示如何将 Universal Database MCP Server 与 LM Studio 集成。 ## 概述 LM Studio 是一款用于在本地计算机上运行大型语言模型（LLM）的桌面应用程序。从 0.3.17 版本开始，LM Studio 支持 MCP（Model Context Protocol），允许您通过外部工具扩展其功能。通过集成 Universal Database MCP Server，您可以让 LM Studio 在与本地 AI 模型对话时直接查询和分析数据库数据。 **主要优势：** - 直接从 LM Studio 聊天界面查询数据库 - 使用本地 AI 模型完全离线运行 - 通过自然语言探索数据库结构 - 在对话中执行 SQL 查询并分析结果 - 完全隐私 - 您的数据永远不会离开您的机器 ## 前置要求 - 已安装 [LM Studio](https://lmstudio.ai/)（需要 0.3.17 或更高版本） - 已安装 Node.js 18+ - 数据库实例（MySQL、PostgreSQL、SQLite 等） ## 配置 LM Studio 使用 MCP stdio 模式进行工具集成。配置通过应用程序设置完成。 ### 步骤 1: 打开 LM Studio 设置 1. 启动 LM Studio 2. 点击侧边栏或菜单中的设置图标（齿轮图标） 3. 导航到 **Plugins > MCP Servers** ### 步骤 2: 添加 MCP 服务器配置 在 MCP 服务器配置部分，添加以下 JSON 配置： #### 基本配置 ```json { "mcpServers": { "universal-db-mcp": { "command": "npx", "args": [ "universal-db-mcp", "--type", "mysql", "--host", "localhost", "--port", "3306", "--user", "root", "--password", "your_password", "--database", "your_database" ] } } } ``` ### 步骤 3: 保存并重启 添加配置后，保存设置并重启 LM Studio 以使更改生效。 ## 配置示例 ### MySQL ```json { "mcpServers": { "mysql-db": { "command": "npx", "args": [ "universal-db-mcp", "--type", "mysql", "--host", "localhost", "--port", "3306", "--user", "root", "--password", "your_password", "--database", "your_database" ] } } } ``` ### PostgreSQL ```json { "mcpServers": { "postgres-db": { "command": "npx", "args": [ "universal-db-mcp", "--type", "postgres", "--host", "localhost", "--port", "5432", "--user", "postgres", "--password", "your_password", "--database", "your_database" ] } } } ``` ### SQLite ```json { "mcpServers": { "sqlite-db": { "command": "npx", "args": [ "universal-db-mcp", "--type", "sqlite", "--file-path", "/path/to/your/database.db" ] } } } ``` ### SQL Server ```json { "mcpServers": { "sqlserver-db": { "command": "npx", "args": [ "universal-db-mcp", "--type", "sqlserver", "--host", "localhost", "--port", "1433", "--user", "sa", "--password", "your_password", "--database", "your_database" ] } } } ``` ### Oracle ```json { "mcpServers": { "oracle-db": { "command": "npx", "args": [ "universal-db-mcp", "--type", "oracle", "--host", "localhost", "--port", "1521", "--user", "system", "--password", "your_password", "--database", "ORCL" ] } } } ``` ### MongoDB ```json { "mcpServers": { "mongodb": { "command": "npx", "args": [ "universal-db-mcp", "--type", "mongodb", "--host", "localhost", "--port", "27017", "--user", "admin", "--password", "your_password", "--database", "your_database" ] } } } ``` ### Redis ```json { "mcpServers": { "redis": { "command": "npx", "args": [ "universal-db-mcp", "--type", "redis", "--host", "localhost", "--port", "6379", "--password", "your_password" ] } } } ``` ### 达梦数据库 ```json { "mcpServers": { "dm-db": { "command": "npx", "args": [ "universal-db-mcp", "--type", "dm", "--host", "localhost", "--port", "5236", "--user", "SYSDBA", "--password", "your_password", "--database", "DAMENG" ] } } } ``` ### 人大金仓 ```json { "mcpServers": { "kingbase-db": { "command": "npx", "args": [ "universal-db-mcp", "--type", "kingbase", "--host", "localhost", "--port", "54321", "--user", "system", "--password", "your_password", "--database", "your_database" ] } } } ``` ### 多数据库配置 您可以配置多个数据库连接： ```json { "mcpServers": { "mysql-production": { "command": "npx", "args": [ "universal-db-mcp", "--type", "mysql", "--host", "prod-db.example.com", "--port", "3306", "--user", "readonly_user", "--password", "prod_password", "--database", "production_db" ] }, "mysql-development": { "command": "npx", "args": [ "universal-db-mcp", "--type", "mysql", "--host", "localhost", "--port", "3306", "--user", "root", "--password", "dev_password", "--database", "development_db" ] }, "postgres-analytics": { "command": "npx", "args": [ "universal-db-mcp", "--type", "postgres", "--host", "analytics-db.example.com", "--port", "5432", "--user", "analyst", "--password", "analytics_password", "--database", "analytics" ] } } } ``` ### 启用写操作 默认情况下，为安全起见禁用写操作。要启用写操作： ```json { "mcpServers": { "mysql-db-writable": { "command": "npx", "args": [ "universal-db-mcp", "--type", "mysql", "--host", "localhost", "--port", "3306", "--user", "root", "--password", "your_password", "--database", "your_database", "--allow-write", "true" ] } } } ``` > **警告**：启用写操作允许 AI 执行 INSERT、UPDATE、DELETE 和其他修改查询。请谨慎使用，尤其是在生产环境中。 ## 可用工具 配置完成后，以下 MCP 工具将在 LM Studio 中可用： | 工具 | 描述 | |------|------| | `execute_query` | 对数据库执行 SQL 查询 | | `get_schema` | 获取数据库结构信息（表、列、类型） | | `get_table_info` | 获取特定表的详细信息 | | `clear_cache` | 清除 Schema 缓存 | ## 使用示例 ### 示例 1: 探索数据库结构 在 LM Studio 聊天中，您可以询问： ``` 我的数据库中有哪些表？ ``` AI 将使用 `get_schema` 工具检索并显示您的数据库结构。 ### 示例 2: 查询数据 让 AI 查询您的数据： ``` 显示 orders 表中最近的 10 条订单 ``` AI 将生成并执行适当的 SQL 查询： ```sql SELECT * FROM orders ORDER BY created_at DESC LIMIT 10 ``` ### 示例 3: 编写 SQL 查询 获取编写复杂查询的帮助： ``` 编写一个查询，找出按总订单金额排名前 5 的客户 ``` AI 将分析您的结构并生成： ```sql SELECT c.id, c.name, SUM(o.total_amount) as total_value FROM customers c JOIN orders o ON c.id = o.customer_id GROUP BY c.id, c.name ORDER BY total_value DESC LIMIT 5 ``` ### 示例 4: 数据分析 让 AI 分析您的数据： ``` 分析过去 6 个月的销售趋势 ``` AI 将查询相关表并根据数据提供洞察。 ### 示例 5: 生成报表 请求数据汇总： ``` 生成 2024 年按月份统计的用户注册汇总 ``` AI 将创建并执行适当的查询来生成报表。 ## 命令行参数 | 参数 | 必填 | 描述 | |------|------|------| | `--type` | 是 | 数据库类型：mysql、postgres、sqlite、sqlserver、oracle、mongodb、redis、dm、kingbase、gaussdb、oceanbase、tidb、clickhouse、polardb、vastbase、highgo、goldendb | | `--host` | 是* | 数据库主机 | | `--port` | 否 | 数据库端口（不指定则使用默认端口） | | `--user` | 是* | 数据库用户名 | | `--password` | 是* | 数据库密码 | | `--database` | 是* | 数据库名称 | | `--file-path` | 是* | SQLite 文件路径（仅 sqlite 类型） | | `--allow-write` | 否 | 启用写操作（默认：false） | | `--oracle-client-path` | 否 | Oracle Instant Client 路径（用于 Oracle 11g） | *必填字段取决于数据库类型 ## 最佳实践 ### 1. 安全性 - **使用只读数据库用户**访问生产数据库 - **切勿分享**包含真实凭据的配置 - **尽可能使用环境变量**存储敏感数据 - **限制数据库权限**仅授予必要的权限 ### 2. 性能 - 使用具体查询而非 `SELECT *` - 添加 `LIMIT` 子句以防止大结果集 - 考虑使用只读副本进行大量查询 ### 3. 模型选择 - 选择具有良好指令遵循能力的模型以获得更好的工具使用效果 - 较大的模型通常在处理复杂数据库查询时表现更好 - 测试不同的模型以找到速度和准确性之间的最佳平衡 ### 4. 使用技巧 - 在查询中尽量具体以获得更好的结果 - 使用自然语言描述您需要的数据 - 需要时让 AI 解释查询结果 ## 故障排除 ### 问题：MCP 服务器未连接 **症状**：LM Studio 无法识别数据库工具 **解决方案**： 1. 验证 LM Studio 版本是否为 0.3.17 或更高 2. 检查 MCP 服务器配置是否正确输入到 Plugins > MCP Servers 3. 验证 JSON 语法是否有效（无尾随逗号、正确的引号） 4. 更改配置后重启 LM Studio 5. 确保 Node.js 已安装并可从 PATH 访问 ### 问题：连接被拒绝 **症状**：关于连接被拒绝的错误消息 **解决方案**： 1. 验证数据库主机和端口是否正确 2. 检查数据库服务器是否正在运行 3. 确保防火墙允许连接到数据库端口 4. 验证到数据库主机的网络连接 ### 问题：认证失败 **症状**：关于无效凭据的错误消息 **解决方案**： 1. 仔细检查用户名和密码 2. 验证用户是否有权访问指定的数据库 3. 检查数据库是否需要 SSL/TLS 连接 4. 确保用户可以从您的 IP 地址连接 ### 问题：权限被拒绝 **症状**：查询因权限错误而失败 **解决方案**： 1. 验证数据库用户是否具有 SELECT 权限 2. 检查特定表是否需要额外权限 3. 对于写操作，确保设置了 `--allow-write` 且用户具有写权限 ### 问题：查询缓慢 **症状**：查询执行时间过长 **解决方案**： 1. 为数据库表添加适当的索引 2. 使用 `LIMIT` 子句限制结果集 3. 优化复杂查询 4. 考虑使用只读副本 ### 问题：找不到 npx 命令 **症状**：错误提示 npx 未被识别 **解决方案**： 1. 安装 Node.js（版本 18 或更高） 2. 确保 Node.js bin 目录在系统 PATH 中 3. 尝试使用 npx 的完整路径 4. 在 Windows 上，安装 Node.js 后可能需要重启 ### 问题：模型不使用工具 **症状**：即使被要求，AI 模型也不使用数据库工具 **解决方案**： 1. 确保您使用的模型支持函数调用/工具使用 2. 尝试在提示中更明确（例如，"使用数据库工具来..."） 3. 检查 MCP 服务器是否在 LM Studio 设置中正确连接 4. 尝试使用具有更好工具使用能力的不同模型 ## 资源 - [LM Studio 官方网站](https://lmstudio.ai/) - [LM Studio 文档](https://lmstudio.ai/docs) - [Universal Database MCP Server 文档](../README.zh-CN.md) - [MCP 协议规范](https://modelcontextprotocol.io/) ## 支持 如有集成问题： - GitHub Issues: https://github.com/Anarkh-Lee/universal-db-mcp/issues - LM Studio Discord: https://discord.gg/lmstudio