Talk SQL MCP Server

🗄️ 谈sql

谈sql 是一个 模型上下文协议（MCP） 服务器，为AI助手（Cursor、Claude、Copilot等）提供完整的本地SQL数据库访问权限，而无需使用Docker命令或shell解决方法。

支持 PostgreSQL, MySQL, SQL Server，以及 SQLite 通过一套统一的工具。

______________________________________________________________________

✨ 特性

支持： PostgreSQL·MySQL·SQL Server·SQLite·IBM DB2

______________________________________________________________________

📦 安装

选项1-npx（无需安装）

直接运行，无需全局安装任何东西：

npx talk-sql

这是人工智能客户端配置的推荐方法。

选项2——全局安装

npm install -g talk-sql
talk-sql

选项3——来源

git clone https://github.com/Edavi11/talk-sql-mcp-server.git
cd talk-sql-mcp-server
npm install
npm run build
npm link        # Makes talk-sql available globally

Windows注意事项： 如果 better-sqlite3 在安装过程中失败（本机C++绑定），如果您没有使用SQLite，可以安全地忽略它。该服务器在没有它的情况下完全适用于PostgreSQL、MySQL和SQL server。

______________________________________________________________________

🚀 运行服务器

stdio模式（默认-由Cursor、Claude Desktop等使用）

npx talk-sql

HTTP模式（用于远程或多客户端使用）

TRANSPORT=http PORT=3000 npx talk-sql

服务器将在以下时间可用 http://localhost:3000/mcp.

开发（自动重新加载，从源代码）

npm run dev

______________________________________________________________________

🔧 AI客户端的配置

多个连接（推荐）

建议的方法是在一个JSON配置文件中定义所有数据库，并将sql指向它。这样，您只需要 一个MCP服务器条目 无论您使用多少数据库。

步骤1——创建配置文件 （例如。 ~/talk-sql.config.json):

[
  {
    "name": "local",
    "connectionString": "postgresql://user:password@localhost:5432/mydb"
  },
  {
    "name": "production",
    "connectionString": "postgresql://user:password@prod-server:5432/mydb"
  }
]

步骤2——配置MCP客户端 指向该文件：

{
  "mcpServers": {
    "talk-sql": {
      "command": "npx",
      "args": ["-y", "talk-sql"],
      "env": {
        "TALK_SQL_CONFIG": "/absolute/path/to/talk-sql.config.json"
      }
    }
  }
}

然后，AI可以使用 db_list_connections 发现可用连接并使用 connection_name 在任何工具调用中：

db_ping(connection_name="local")
db_query(connection_name="production", query="SELECT * FROM users LIMIT 10")

______________________________________________________________________

ssh隧道

配置文件中的连接可以包括 ssh 阻塞以通过SSH隧道路由流量。适用于无法从您的计算机直接访问的数据库。

使用私钥：

[
  {
    "name": "remote-db",
    "connectionString": "postgresql://postgres:pass@localhost:5432/mydb",
    "ssh": {
      "host": "185.207.250.95",
      "port": 22,
      "username": "root",
      "privateKeyPath": "~/.ssh/id_rsa"
    }
  }
]

使用密码：

[
  {
    "name": "remote-db",
    "connectionString": "postgresql://postgres:pass@localhost:5432/mydb",
    "ssh": {
      "host": "185.207.250.95",
      "port": 22,
      "username": "root",
      "password": "my-ssh-password"
    }
  }
]

注： 这 connectionString 应使用所示的主机名 从SSH服务器。如果数据库与SSH服务器在同一台机器上运行，请使用 localhost。如果它在同一专用网络中的不同机器上运行，请使用其内部IP。

______________________________________________________________________

单连接（传统/简单设置）

如果你只有一个数据库，你可以跳过配置文件并设置 SQL_CONNECTION_STRING 直接：

光标

添加 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "talk-sql": {
      "command": "npx",
      "args": ["-y", "talk-sql"],
      "env": {
        "SQL_CONNECTION_STRING": "mssql://user:password@localhost:1433/MyDatabase?encrypt=false&trustServerCertificate=true"
      }
    }
  }
}

克劳德桌面版

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "talk-sql": {
      "command": "npx",
      "args": ["-y", "talk-sql"],
      "env": {
        "SQL_CONNECTION_STRING": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

______________________________________________________________________

全局安装（启动速度更快）

如果你想避免 npx 每次启动时的解析开销，全局安装一次：

npm install -g talk-sql

然后使用 "command": "talk-sql" 而不是 "command": "npx" 在您的客户端配置中。

______________________________________________________________________

🔌 连接串

🐘 PostgreSQL

postgresql://user:password@localhost:5432/database

🐬 MySQL

mysql://user:password@localhost:3306/database

🪟 SQL Server

mssql://user:password@localhost:1433/database?encrypt=false&trustServerCertificate=true

🪶 SQLite

sqlite:///absolute/path/to/database.db

🔵 IBM DB2

db2://user:password@localhost:50000/DATABASE

注： IBM DB2支持需要 ibm_db 包装(npm install ibm_db).这是一个可选的依赖关系——服务器在没有它的情况下对所有其他数据库都有效。在安装期间， ibm_db 自动下载IBM ODBC CLI驱动程序（约100 MB）。

______________________________________________________________________

🛠️ 可用工具

db_list_connections

列出配置文件中配置的所有命名连接。首先使用此选项可发现可用的连接名称。

{
  "response_format": "json"
}

示例响应：

{
  "connections": [
    { "name": "local", "type": "postgresql", "has_ssh": false },
    { "name": "remote-db", "type": "postgresql", "has_ssh": true }
  ],
  "total": 2,
  "note": "Use connection_name parameter in other tools to specify which connection to use."
}

______________________________________________________________________

db_ping

测试连接并返回服务器版本和延迟。 先用这个 在诊断连接问题时。

{
  "connection_name": "local",
  "response_format": "json"
}

______________________________________________________________________

db_list_databases

返回服务器上所有可用的数据库。

{
  "connection_name": "local",
  "response_format": "json"
}

______________________________________________________________________

db_list_tables

返回数据库中的所有模式及其表。

{
  "connection_name": "local",
  "response_format": "markdown"
}

______________________________________________________________________

db_query

执行任何SQL语句——SELECT、INSERT、UPDATE、DELETE、DDL或SQL Server批处理脚本（使用 GO 分离器）。

{
  "connection_name": "production",
  "query": "SELECT id, name, email FROM users WHERE active = true LIMIT 20",
  "response_format": "markdown"
}

______________________________________________________________________

db_select

从具有内置分页、列筛选和WHERE子句支持的表中选择数据。手柄 LIMIT/OFFSET 对比 OFFSET/FETCH 每个数据库自动。

{
  "connection_name": "local",
  "table": "orders",
  "schema": "public",
  "columns": ["id", "customer_id", "total", "created_at"],
  "where": "status = 'pending'",
  "limit": 50,
  "offset": 0,
  "response_format": "json"
}

______________________________________________________________________

db_create_table

创建一个包含列、类型、约束和自动增量的新表——自动映射到正确的数据库语法。

{
  "connection_name": "local",
  "table": "products",
  "columns": [
    { "name": "id", "type": "INT", "primary_key": true, "auto_increment": true },
    { "name": "name", "type": "VARCHAR(255)", "nullable": false },
    { "name": "price", "type": "DECIMAL(10,2)", "nullable": false },
    { "name": "created_at", "type": "DATETIME", "default": "GETDATE()" }
  ],
  "response_format": "json"
}

______________________________________________________________________

db_create_relation

在表之间添加外键约束。

{
  "connection_name": "local",
  "table": "orders",
  "foreign_keys": [
    {
      "column": "user_id",
      "references_table": "users",
      "references_column": "id",
      "on_delete": "CASCADE",
      "on_update": "NO ACTION"
    }
  ],
  "response_format": "json"
}

______________________________________________________________________

db_create_trigger

创建具有定时和事件控制的数据库触发器。语法会自动适应每个数据库引擎。

{
  "connection_name": "local",
  "table": "orders",
  "trigger_name": "trg_orders_audit",
  "timing": "AFTER",
  "event": "INSERT",
  "procedure": "INSERT INTO audit_log (table_name, action, created_at) VALUES ('orders', 'INSERT', NOW());",
  "response_format": "json"
}

______________________________________________________________________

🔄 连接解析优先级

当调用工具时，talk sql按以下顺序解析连接：

______________________________________________________________________

🔄 响应格式

所有工具都支持两种输出格式 response_format 参数：

______________________________________________________________________

🧠 AI助手行为

该服务器的设计使AI助手 总是有前进的道路 当某事失败时：

• 每个错误响应都包含一个 下一步 带有具体恢复说明的部分
• db_ping 根据错误类型（身份验证、网络、SSL、缺少数据库等）提供有针对性的建议
• 工具描述明确地告诉AI 使用MCP工具重试 而不是回到Docker或shell命令
• db_list_connections 让AI在进行任何DB调用之前发现可用的连接

______________________________________________________________________

🏗️ 项目结构

src/
├── index.ts                    # MCP server entry point, tool registration
├── types.ts                    # Shared TypeScript types and enums
├── constants.ts                # Limits, connection resolution logic
├── schemas/
│   └── connection.ts           # Zod validation schemas
├── services/
│   ├── connection-manager.ts   # Connection pooling for all DB types
│   ├── query-executor.ts       # Query execution and result formatting
│   └── ssh-tunnel.ts           # SSH tunnel support
└── tools/
    ├── database-tools.ts       # db_ping, db_list_databases, db_list_tables, db_list_connections
    ├── query-tools.ts          # db_query, db_select
    ├── ddl-tools.ts            # db_create_table, db_create_relation
    └── trigger-tools.ts        # db_create_trigger

______________________________________________________________________

📄 许可证

麻省理工学院