NLSQL MCP Server

NLSQL MCP服务器

一个MCP（模型上下文协议）服务器，它公开了 nl2sql 作为MCP工具的SQL应用程序的自然语言。这允许任何兼容MCP的客户端使用AI将自然语言问题转换为SQL查询。

特性

• 数据库连接：连接到SQLite、PostgreSQL和MySQL数据库
• 模式分析：自动分析数据库结构和关系
• 自然语言到SQL：使用AI将普通英语问题转换为SQL查询
• 查询执行：使用可配置的限制安全执行SQL查询
• 查询验证：执行前验证SQL语法
• 样品数据：从数据库表中访问示例数据
• 内置提示：常见数据库任务的预配置提示

先决条件

1. NLSQL应用程序：此MCP服务器是围绕 nl2sql应用程序.你 必须先安装nl2sql.
2. OpenAI API密钥：自然语言到SQL转换所需
3. Python 3.8+：与Python 3.8及以上版本兼容

安装

步骤1:安装NLSQL应用程序（必需）

此MCP服务器需要先安装原始的nl2sql应用程序。

# Clone the original nl2sql application
git clone https://github.com/tushar-badhwar/nl2sql.git
cd nl2sql

# Install dependencies
pip install -r requirements.txt

# Test the installation
streamlit run main.py

步骤2：安装MCP服务器

# Navigate to the same parent directory where nl2sql is located
cd ..  # Now you should be in the directory containing nl2sql/

# Clone this MCP server
git clone https://github.com/tushar-badhwar/nlsql-mcp-server.git
cd nlsql-mcp-server

# Install MCP server dependencies
pip install -r requirements.txt

# Or install in development mode
pip install -e .

步骤3：环境设置

# Set your OpenAI API key
export OPENAI_API_KEY="your_api_key_here"

# Or create a .env file
echo "OPENAI_API_KEY=your_api_key_here" > .env

步骤4：验证目录结构

确保您的目录结构如下：

parent_directory/
├── nl2sql/                # Original nl2sql application (required dependency)
│   ├── main.py
│   ├── database_manager.py
│   ├── crew_setup.py
│   ├── agents.py
│   ├── tasks.py
│   └── nba.sqlite
└── nlsql-mcp-server/      # This MCP server
    ├── src/
    ├── tests/
    ├── README.md
    └── requirements.txt

重要：MCP服务器会自动在父目录中查找nl2sql目录。如果您有不同的设置，可能需要调整中的路径 src/nlsql_mcp_server/nlsql_client.py.

运行服务器

单独模式

# Run the server directly
python -m nlsql_mcp_server.server

# Or using the console script (after pip install)
nlsql-mcp-server

使用MCP客户端

配置您的MCP客户端以使用此服务器。配置示例：

{
  "mcpServers": {
    "nlsql": {
      "command": "python",
      "args": ["-m", "nlsql_mcp_server.server"],
      "cwd": "/path/to/nlsql-mcp-server",
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

可用工具

数据库连接工具

connect_database

连接到SQLite、PostgreSQL或MySQL数据库。

参数：

• db_type （必填）：“sqlite”、“postgresql”或“mysql”
• file_path：SQLite文件的路径（仅限SQLite）
• host, port, database, username, password：连接详细信息（PostgreSQL/MySQL）

connect_sample_database

连接到内置的NBA样本数据库进行测试。

模式分析工具

analyze_schema

使用AI分析数据库模式和结构。

参数：

• force_refresh （可选）：强制刷新架构缓存

get_database_info

获取详细的数据库信息，包括表、列和关系。

get_table_sample

从特定表中获取示例数据。

参数：

• table_name （必填）：表格名称
• limit （可选）：要返回的行数（默认值：5）

自然语言到SQL工具

natural_language_to_sql

使用AI将自然语言问题转换为SQL查询。

参数：

• question （必填）：自然语言问题
• skip_schema （可选）：跳过模式分析以加快处理速度

SQL执行工具

execute_sql_query

对连接的数据库执行SQL查询。

参数：

• sql_query （必填）：要执行的SQL查询
• limit （可选）：要返回的最大行数（默认值：100）

validate_sql_query

验证SQL查询语法和结构。

参数：

• sql_query （必填）：要验证的SQL查询

实用工具

get_connection_status

获取当前数据库连接状态。

disconnect_database

断开与当前数据库的连接。

可用提示

analyze_database

全面的数据库分析工作流程。

generate_sql_query

自然语言到SQL生成工作流。

troubleshoot_sql

SQL查询疑难解答工作流。

使用示例

与Claude Desktop一起使用

1. 配置Claude Desktop以使用此MCP服务器

1. 连接到数据库：

   Use the connect_sample_database tool to connect to the NBA sample database

1. 问自然语言问题：

   Use the natural_language_to_sql tool with the question "How many teams are in the NBA?"

1. 执行查询：

   Use the execute_sql_query tool to run the generated SQL

工作流示例

1. 连接: connect_sample_database
2. 分析: analyze_schema
3. 查询: natural_language_to_sql 问题是“列出来自加利福尼亚的所有球队”
4. 执行: execute_sql_query 使用生成的SQL
5. 探索: get_table_sample 用于额外的数据探索

高级用法

自定义数据库连接

{
  "tool": "connect_database",
  "arguments": {
    "db_type": "postgresql",
    "host": "localhost",
    "port": 5432,
    "database": "mydb",
    "username": "user",
    "password": "password"
  }
}

性能优化

• 使用 skip_schema: true 在……里面 natural_language_to_sql 在初始模式分析后进行更快的查询
• 设置适当 limit 大型结果集的值
• 使用 get_table_sample 在编写复杂查询之前探索数据

故障排除

常见问题

1. “找不到nl2sql应用程序”或“未找到nlsql模块”

- 解决方案：首先安装原始的nl2sql应用程序 - 命令: git clone https://github.com/tushar-badhwar/nl2sql.git - 验证：检查一下 nl2sql/database_manager.py 存在 - 结构：确保两者 nl2sql/ 和 nlsql-mcp-server/ 位于同一父目录中

1. “找不到OpenAI API密钥”

- 设置OPENAI_API_KEY环境变量 - 验证API密钥是否有效

1. 数据库连接失败

- 检查数据库凭据和连接 - 确保数据库服务器正在运行 - 验证远程数据库的防火墙设置

1. 导入错误

- 安装所有必需的依赖项： pip install -r requirements.txt - 检查Python版本兼容性（3.8+）

调试模式

启用调试日志记录：

export PYTHONPATH=/path/to/nlsql-mcp-server/src
python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from nlsql_mcp_server.server import main
import asyncio
asyncio.run(main())
"

测试

该存储库包括全面的测试来验证您的设置：

# Basic functionality test (no API key required)
python3 tests/test_basic.py

# Full setup validation
python3 tests/test_setup.py

# AI functionality test (requires OpenAI API key)
python3 tests/test_with_api.py

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

发展

项目结构

src/
├── nlsql_mcp_server/
│   ├── __init__.py
│   ├── server.py          # Main MCP server
│   ├── tools.py           # MCP tool definitions
│   └── nlsql_client.py    # Interface to nlsql app
├── pyproject.toml
└── requirements.txt

添加新工具

1. 在中定义工具 tools.py
2. 在中添加处理程序方法 NLSQLTools.call_tool()
3. 实现中的功能 nlsql_client.py
4. 更新文档

测试

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run type checking
mypy src/

# Format code
black src/
isort src/

许可证

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

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

支持

对于问题和疑问：

• 在GitHub存储库中创建问题
• 检查上面的故障排除部分
• 查看nlsql应用程序文档