SQL Talk

自然言語をSQLに変換するModel Context Protocol（MCP）サーバーです。
Cursorエディターとの統合により、日本語でデータベース操作が可能になります。

作成意図

• 自然言語でのデータベース操作: 複雑なSQLを覚える必要なく、日本語でデータベースにアクセス
• 安全性の確保: 危険な操作を自動的にブロックし、PII情報を保護
• 開発効率の向上: CursorエディターでAIと会話しながらデータベース作業を実行
• 日本語コメント生成: 英語のスキーマに自動で適切な日本語コメントを付与

前提条件

重要: このシステムを使用するには、ローカル環境に以下のいずれかのデータベースが必要です。

• MySQL 8.0以上 または
• PostgreSQL 12以上

データベースが未インストールの場合は、事前にインストールしてください。

導入方法

1. Cursor MCPの設定

Cursorの設定ファイル（~/.cursor/mcp.json）に以下を追加：

{
  "mcpServers": {
    "sql-talk": {
      "command": "npx",
      "args": ["sql-talk@latest"]
    }
  }
}

2. 設定ファイルの作成

プロジェクトルートにsql-talk.config.ymlを作成します。
初回はサンプルをコピーして編集すると便利です：

cp sql-talk.config.yml.sample sql-talk.config.yml
# エディタで sql-talk.config.yml を開き、接続先などを編集

サンプル（sql-talk.config.yml.sample）には各項目の説明と設定の流れをコメントで記載しています。

ローカルデータベースの場合

engine: mysql  # または postgres
connections:
  read_only:
    host: localhost
    port: 3306   # PostgreSQLの場合は5432
    user: your_username
    password: your_password
    # 単一DB: database を指定
    database: your_database
    # 複数DB（許可リスト）: databases を指定すると、スキーマ取得・参照はこのリストに制限される
    # databases:
    #   - your_database
    #   - other_database
  ddl_comment:
    host: localhost
    port: 3306
    user: your_username
    password: your_password
    database: your_database

limits:
  default_limit: 100
  max_limit: 1000

pii:
  column_patterns: []
  masking:
    enabled: true
    strategy: partial

接続してよいデータベースの指定

• database: 1つだけ指定する場合（従来どおり）。接続のデフォルトDBになり、スキーマ取得もこのDBのみ。
• databases: 複数指定する場合。ここに列挙したDBだけがスキーマ取得・参照の対象になる（閲覧権限があってもリスト外のDBは見えない）。
• どちらか一方を必ず指定すること。databases を指定すると、接続のデフォルトDBは先頭の要素になる。

SSHトンネル経由でリモートデータベースにアクセスする場合

# データベース接続設定
database:
  read_only:
    type: mysql
    host: localhost
    port: 13306  # SSHトンネルのローカルポート
    user: your_username
    password: your_password
    database: your_database
  
  ddl_comment:
    type: mysql
    host: localhost
    port: 13306
    user: your_username
    password: your_password
    database: your_database

# SSHトンネル設定
ssh_tunnels:
  mysql-tunnel:
    ssh_host: your-server.com
    ssh_port: 22
    ssh_user: your_ssh_user
    ssh_private_key_path: ~/.ssh/id_rsa
    # ssh_password: your_ssh_password  # 鍵認証の代わりにパスワード認証を使う場合
    local_port: 13306
    remote_host: localhost  # リモートサーバー上のDBホスト
    remote_port: 3306       # リモートサーバー上のDBポート
    auto_start: true

# セキュリティ設定
limits:
  default_limit: 100
  max_limit: 1000

# PII保護設定
pii:
  masking_enabled: true
  strategy: partial

各ツールの説明

スキーマ管理

• describe_schema: データベーススキーマの確認
• refresh_schema: スキーマキャッシュの更新

SQL操作

• propose_sql: 自然言語からSQL生成
• lint_sql: SQLの安全性チェック
• explain_sql: SQL実行計画の表示
• execute_readonly: 安全なSELECTクエリの実行

コメント管理

• propose_missing_comments: 日本語コメントの自動生成
• render_comment_sql: コメント適用用SQL生成
• apply_comment_sql: コメントの実際の適用

設定管理

• update_config: 設定の動的変更

使用例

Cursorで以下のような日本語での質問が可能です：

「ユーザー一覧を取得して」
「売上の多い商品トップ10を教えて」
「今月の注文件数は？」
「business_partnersテーブルにコメントを追加して」

安全機能

• 操作制限: SELECT以外の危険な操作は自動ブロック
• PII保護: 個人情報の自動マスキング
• クエリ制限: 結果件数の上限設定
• 監査ログ: 全操作の記録

トラブルシューティング

データベース接続エラー

• MySQL/PostgreSQLが起動しているか確認
• 接続情報（ホスト、ポート、ユーザー、パスワード）を確認
• データベースが存在するか確認

MCPサーバーが起動しない

• Node.js 20.0.0以上がインストールされているか確認
• sql-talk.config.ymlが正しい場所にあるか確認
• 設定ファイルの構文エラーがないか確認

Cursorで認識されない

• Cursorを再起動
• MCP設定ファイルの構文を確認
• ログでエラーメッセージを確認

ライセンス

MIT License

サポート

問題が発生した場合は、以下を確認してください：

1. データベースサーバーの状態
2. 設定ファイルの内容
3. Cursorのログメッセージ