# mcp-server-nodejs-example

**Repository Path**: feng-kailong/mcp-server-nodejs-example

## Basic Information

- **Project Name**: mcp-server-nodejs-example
- **Description**: nodejs的mcp-server的ts示例项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-06
- **Last Updated**: 2026-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MySQL MCP Server

基于 Node.js + TypeScript 的 MySQL MCP 服务，支持连接数据库、查看/创建/删除数据表，以及增删改查操作。

## 技术栈

- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) — MCP TypeScript SDK（stdio 传输）
- [mysql2](https://www.npmjs.com/package/mysql2) — MySQL 连接与查询
- [zod](https://www.npmjs.com/package/zod) — 工具参数校验与字段描述

## 快速开始

### 安装依赖

```bash
cd nodejs-project
npm install
```

### 编译

```bash
npm run build
```

### 开发模式

```bash
npm run dev
```

## Cursor MCP 注册

在 `.cursor/mcp.json` 或全局 `~/.cursor/mcp.json` 中添加配置。`command` 使用 `npx`，通过 `env` 传入数据库连接信息。

### 本地开发（推荐）

```json
{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "tsx", "src/index.ts"],
      "cwd": "D:/application/my/mcp-test/nodejs-project",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "test"
      }
    }
  }
}
```

### 使用编译产物

```json
{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "node", "dist/index.js"],
      "cwd": "D:/application/my/mcp-test/nodejs-project",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "test"
      }
    }
  }
}
```

### 发布到 npm 后

```json
{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "mysql-mcp-server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "test"
      }
    }
  }
}
```

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `MYSQL_HOST` | 是 | — | MySQL 服务器地址 |
| `MYSQL_PORT` | 否 | `3306` | MySQL 端口 |
| `MYSQL_USER` | 是 | — | 数据库用户名 |
| `MYSQL_PASSWORD` | 是 | — | 数据库密码 |
| `MYSQL_DATABASE` | 是 | — | 要连接的数据库名 |

配置了上述环境变量后，服务启动时会**自动连接**数据库，无需每次手动调用 `connect_db`。仍可通过 `connect_db` 切换到其他数据库。

## 工具说明

所有工具的 `title`、`description` 以及参数字段的 `description` 定义在 `src/index.ts` 的 `server.registerTool()` 中，通过 Zod 的 `.describe()` 生成 JSON Schema，Client 调用 `tools/list` 时可见。

### connect_db — 连接数据库

手动连接或切换 MySQL 数据库。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `host` | string | 是 | Database host |
| `user` | string | 是 | Database username |
| `password` | string | 是 | Database password |
| `database` | string | 是 | Database name |
| `port` | number | 否 | MySQL port，默认 3306 |

### list_tables — 查看所有表

列出当前数据库中的所有数据表，无参数。

### describe_table — 查看表结构

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `table` | string | 是 | Table name |

### create_table — 创建数据表

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `sql` | string | 是 | Full CREATE TABLE statement |

仅允许以 `CREATE TABLE` 开头的 SQL。

### drop_table — 删除数据表

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `table` | string | 是 | Table name to delete |
| `ifExists` | boolean | 否 | Use IF EXISTS clause，默认 `true` |

### query — 查询（读）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `sql` | string | 是 | SQL SELECT query |
| `params` | array | 否 | Query parameters (optional) |

仅允许：`SELECT`、`SHOW`、`DESCRIBE`、`DESC`、`EXPLAIN`。

### execute — 增删改（写）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `sql` | string | 是 | SQL query (INSERT, UPDATE, DELETE) |
| `params` | array | 否 | Query parameters (optional) |

仅允许：`INSERT`、`UPDATE`、`DELETE`、`REPLACE`。

## 使用示例

### 查询数据

```json
{
  "sql": "SELECT * FROM users WHERE id = ?",
  "params": [1]
}
```

### 插入数据

```json
{
  "sql": "INSERT INTO users (name, email) VALUES (?, ?)",
  "params": ["张三", "zhangsan@example.com"]
}
```

### 创建表

```json
{
  "sql": "CREATE TABLE users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(100) NOT NULL, email VARCHAR(255))"
}
```

### 删除表

```json
{
  "table": "temp_table",
  "ifExists": true
}
```

## 返回格式

所有工具返回 JSON 文本，统一结构如下：

**成功：**

```json
{
  "success": true,
  "data": { ... },
  "message": "可选提示信息"
}
```

**失败：**

```json
{
  "success": false,
  "error": "错误信息"
}
```

## 项目结构

```
nodejs-project/
├── src/
│   ├── index.ts    # MCP 服务入口，工具注册与字段描述
│   ├── db.ts       # MySQL 连接池管理
│   └── utils.ts    # SQL 校验、响应格式化
├── dist/           # 编译输出
├── package.json
├── tsconfig.json
└── .cursor/
    └── mcp.json    # Cursor MCP 配置示例
```

## 修改字段说明

工具说明和参数字段解释均在 `src/index.ts` 中维护：

- **工具说明**：`registerTool` 第二个参数中的 `title` 和 `description`
- **字段说明**：`inputSchema` 里 Zod 字段的 `.describe("...")`

修改后重新编译（`npm run build`）或重启开发服务即可生效。

## 注意事项

1. MCP stdio 模式下，**不要**向 `stdout` 输出日志，否则会破坏 JSON-RPC 通信；日志请使用 `console.error` 输出到 `stderr`。
2. `drop_table` 和 `execute` 具有破坏性，请在生产环境谨慎使用。
3. 表名仅允许字母、数字、下划线和点（`[\w.]+`），防止 SQL 注入。
4. 需要 Node.js >= 18。