# MySQL MCP Server

MySQL Model Context Protocol（MCP）サーバーは、ローカル環境のMySQLデータベースに接続し、大規模言語モデル（LLM）がSQLクエリを実行できるようにするツールです。

## 要件

- **Node.js**: 20.0.0以上
- **MySQL**: 5.7以上のMySQLまたはMariaDBサーバー

## 機能

- **MySQLクエリの実行**: LLMからSQLクエリを直接実行
- **データベース情報の取得**: データベース一覧、テーブル一覧、テーブル構造の確認
- **MCP準拠**: Model Context Protocol に対応し、LLMと統合可能
- **stdio通信**: 標準入出力を使用してLLMと通信、ポートバインドなし
- **接続プロファイル管理**: 複数の接続設定をプロファイル名で管理し切り替え
- **接続情報の保存**: データベース接続情報をローカルに保存し再利用

## インストールと使用方法

### NPXでの一時実行

```bash
 npx -y https://github.com/yuki777/mysql-mcp-server --host 127.0.0.1 --port 13306 --user root
```

### オプション

| オプション | 説明 | デフォルト値 |
|----------|------|-------------|
| `-h, --host <host>` | MySQLホスト | localhost |
| `-p, --port <port>` | MySQLポート | 13306 |
| `-u, --user <user>` | MySQLユーザー | root |
| `--password <password>` | MySQLパスワード | (空文字) |
| `-d, --database <database>` | デフォルトデータベース | (オプション) |
| `-c, --config <path>` | 設定ファイルパス | (オプション) |
| `--auto-connect` | サーバー起動時に自動的にデータベースに接続 | false |
| `--server-port <port>` | MCPサーバーポート（stdioモードでは使用されません） | 3000 |
| `--server-host <host>` | MCPサーバーホスト（stdioモードでは使用されません） | localhost |
| `--query-timeout <ms>` | クエリタイムアウト(ミリ秒) | 30000 |
| `--max-results <count>` | 最大結果行数 | 1000 |
| `--debug` | デバッグモード | false |

### 接続情報の保存と再利用

MySQL MCP Serverは、正常に接続したデータベースの情報を名前付きプロファイルとしてローカルに保存します。これにより、次回の起動時に接続情報を名前で指定して再利用できます。保存された接続情報は、ユーザーのホームディレクトリにある `.mysql-mcp-connections.json` ファイルに保存されます。

各接続プロファイルには以下が含まれます：
- プロファイル名
- ホスト名
- ポート番号
- ユーザー名
- パスワード
- データベース名（設定されている場合）

複数のデータベース接続をプロファイル名で管理し、簡単に切り替えることが可能です。

### 設定ファイルの使用

設定ファイル（JSON形式）を使用して接続情報を設定することもできます：

```json
{
  "server": {
    "port": 3000,
    "host": "localhost"
  },
  "mysql": {
    "host": "localhost",
    "port": 13306,
    "user": "root",
    "password": "yourpassword",
    "database": "mydb"
  },
  "debug": false,
  "queryTimeout": 30000,
  "maxResultSize": 1000
}
```

設定ファイルを使用する場合:

```bash
npx -y https://github.com/yuki777/mysql-mcp-server -c ./mysql-mcp-config.json
```

## 通信方式

MySQL MCP ServerはMCP (Model Context Protocol) に準拠した「stdio」モードで動作します。これにより特定のポートにバインドせず、標準入出力を介して通信します。これには次のような利点があります：

1. **ポート競合の回避**: 特定のポートを使用しないため、ポート競合の問題が発生しません
2. **セキュリティ向上**: ネットワーク通信を使用しないため、ネットワークレベルの攻撃リスクが軽減
3. **簡素なプロセス間通信**: LLMとの通信がシンプル化

### 注意点

- stdioモードでは、JSON形式のメッセージをやり取りします
- 一行に一つのJSONメッセージを送信する必要があります
- エラー情報と接続ログは標準エラー（stderr）に出力されます

## 提供されるMCPツール

### データベース接続管理

| ツール名 | 説明 | 必須パラメータ |
|---------|------|-------------|
| connect_database | データベースに接続します | host, port, user |
| connect_by_profile | 保存済みプロファイル名で接続します | profileName |
| disconnect_database | 現在のデータベース接続を切断します | なし |
| get_connection_status | データベース接続の状態を取得します | なし |

### 接続プロファイル管理

| ツール名 | 説明 | 必須パラメータ |
|---------|------|-------------|
| list_profiles | 保存済みのプロファイル一覧を取得します | なし |
| get_profile | プロファイルの詳細を取得します | profileName |
| add_profile | 新しいプロファイルを追加します | profileName, host, port, user |
| remove_profile | プロファイルを削除します | profileName |

### SQLクエリ操作

| ツール名 | 説明 | 必須パラメータ |
|---------|------|-------------|
| execute_query | MySQLクエリを実行します | query: SQL文 |
| get_databases | 利用可能なデータベースの一覧を取得します | なし |
| get_tables | 指定したデータベース内のテーブル一覧を取得します | database (オプション) |
| describe_table | 指定したテーブルの構造を取得します | table |

## 接続管理機能

MySQL MCP Serverでは、サーバーの起動とデータベース接続を分離することができます。このアプローチにより以下のメリットがあります：

1. **接続情報なしでの起動**: サーバーはデータベース接続情報がなくても起動可能
2. **複数データベースへの接続**: サーバー起動後に異なるデータベースへ接続の切り替えが可能
3. **シンプルなインストール**: `npx -y https://github.com/yuki777/mysql-mcp-server` だけで実行可能

### 接続管理の使用方法

1. **自動接続なしでサーバーを起動**:
   ```bash
   npx -y https://github.com/yuki777/mysql-mcp-server
   ```

2. **接続ツールを使用してデータベースに接続（プロファイル名を指定して保存）**:
   ```json
   {
     "type": "tool_call",
     "request_id": "req_1",
     "tool": "connect_database",
     "arguments": {
       "host": "localhost",
       "port": 3306,
       "user": "root",
       "password": "your_password",
       "database": "your_db",
       "profileName": "my-db"
     }
   }
   ```

3. **プロファイル一覧の取得**:
   ```json
   {
     "type": "tool_call",
     "request_id": "req_2",
     "tool": "list_profiles",
     "arguments": {}
   }
   ```

4. **プロファイル名で接続**:
   ```json
   {
     "type": "tool_call",
     "request_id": "req_3",
     "tool": "connect_by_profile",
     "arguments": {
       "profileName": "my-db"
     }
   }
   ```
   
5. **新しいプロファイルの追加（接続は行わない）**:
   ```json
   {
     "type": "tool_call",
     "request_id": "req_4",
     "tool": "add_profile",
     "arguments": {
       "profileName": "production-db",
       "host": "prod.example.com",
       "port": 3306,
       "user": "prod_user",
       "password": "prod_password",
       "database": "production"
     }
   }
   ```

6. **接続状態の確認**:
   ```json
   {
     "type": "tool_call",
     "request_id": "req_5",
     "tool": "get_connection_status",
     "arguments": {}
   }
   ```

7. **接続の切断**:
   ```json
   {
     "type": "tool_call",
     "request_id": "req_6",
     "tool": "disconnect_database",
     "arguments": {}
   }
   ```

### テスト用スクリプト

リポジトリには `test-connection-management.js` というテストスクリプトが含まれています。このスクリプトを使用して、接続管理機能をテストできます：

```bash
node test-connection-management.js
```

## 開発者向け情報

### 開発環境のセットアップ

```bash
# リポジトリのクローン
git clone [repository-url]
cd mysql-mcp-server

# 依存関係のインストール
npm install

# 開発モードでの実行
npm run dev
```

### ビルド

```bash
npm run build
```

## ライセンス

ISC

## 貢献

バグレポートや機能リクエスト、プルリクエストを歓迎します。