LoginSignup
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@nemoy

SQLcl MCPサーバーでClaude CodeとOracle DBを連携してみる

Last updated at Posted at 2025-08-05

SQLcl 25.2 MCPサーバーでClaudeとOracle DBを連携させる完全ガイド

こんにちは！Oracle SQLcl 25.2に標準搭載されたMCP（Model Context Protocol）サーバー機能を使って、ClaudeからOracle Databaseへ直接アクセスする方法を、環境構築から実際の使用方法まで詳しく解説していきます。

本記事の目的

この記事では以下をやっています：

  • Oracle Database 23ai Free環境の構築
  • SQLcl 25.2のインストールと設定
  • MCP（Model Context Protocol）サーバーの設定
  • ClaudeからOracle DBへの接続と操作方法
  • 実際の使用例とベストプラクティス

環境

アーキテクチャ概要

Claude Code CLI → MCP Server (SQLcl 25.2) → Oracle Database 23ai Free

🗄️ Step 1: Oracle Database 23ai Free環境の構築

1.1 Oracle環境変数の設定

まず、Oracle Database用の環境変数を設定します：

# Oracle Database 23ai Free環境変数(.bashrcに追記）
echo 'export ORACLE_HOME=/opt/oracle/product/23ai/dbhomeFree' >> ~/.bashrc
echo 'export PATH=$ORACLE_HOME/bin:$ORACLE_HOME/sqlcl/bin:$PATH' >> ~/.bashrc
echo 'export ORACLE_SID=FREE' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
echo 'export ORACLE_BASE=/opt/oracle' >> ~/.bashrc
source ~/.bashrc

1.2 データベースの起動確認

Oracle Database 23ai Freeが正常に動作していることを確認：

# データベースインスタンスの起動
sqlplus / as sysdba <<EOF
STARTUP;
SELECT name, open_mode FROM v$database;
EXIT;
EOF

# リスナーの起動確認
lsnrctl status

期待される出力例:

Database opened.
NAME      OPEN_MODE
--------- ----------
FREE      READ WRITE

LSNRCTL for Linux: Version 23.0.0.0.0 - Production on XX-XXX-XXXX XX:XX:XX
Status of the Listener
Listener Parameter File   /opt/oracle/product/23ai/dbhomeFree/network/admin/listener.ora
Listener Log File         /opt/oracle/diag/tnslsnr/hostname/listener/alert/log.xml
Listening Endpoints Summary...
  (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=localhost)(PORT=1521)))

1.3 PDB（Pluggable Database）の設定

Oracle 23ai FreeはContainer Database (CDB)アーキテクチャを使用します。一般ユーザーはPDBに作成する必要があります：

# SYSDBAとしてCDBに接続してPDBを確認
sqlplus / as sysdba <<EOF
-- PDBの状態確認
SHOW PDBS;

-- FREEPDB1が閉じている場合は開く
ALTER PLUGGABLE DATABASE FREEPDB1 OPEN;

-- 自動起動の設定
ALTER PLUGGABLE DATABASE FREEPDB1 SAVE STATE;

EXIT;
EOF

期待される出力例:

    CON_ID CON_NAME                       OPEN MODE  RESTRICTED
---------- ------------------------------ ---------- ----------
         2 PDB$SEED                       READ ONLY  NO
         3 FREEPDB1                       READ WRITE NO

1.4 MCPアクセス用ユーザーの作成

MCP専用のデータベースユーザーを作成します：

# FREEPDB1でMCPユーザーを作成
sqlplus / as sysdba <<EOF
-- FREEPDB1に切り替え
ALTER SESSION SET CONTAINER = FREEPDB1;

-- MCP専用ユーザーの作成
CREATE USER mcp_user IDENTIFIED BY mcp_password;

-- 基本権限の付与
GRANT CONNECT, RESOURCE TO mcp_user;
GRANT CREATE SESSION TO mcp_user;
GRANT SELECT ANY TABLE TO mcp_user;

-- テーブルスペースのクォータ付与（重要！）
ALTER USER mcp_user QUOTA UNLIMITED ON USERS;

-- 作成確認
SELECT username, account_status FROM dba_users WHERE username = 'MCP_USER';

EXIT;
EOF

1.5 サンプルデータの作成

テスト用のemployeesテーブルとサンプルデータを作成：

# mcp_userでPDBに接続してサンプルテーブル作成
echo "-- サンプルテーブルとデータの作成
CREATE TABLE employees (
    id NUMBER PRIMARY KEY,
    name VARCHAR2(100),
    department VARCHAR2(50),
    salary NUMBER
);

-- サンプルデータ挿入
INSERT INTO employees VALUES (1, '田中太郎', '営業部', 500000);
INSERT INTO employees VALUES (2, '佐藤花子', '開発部', 600000);
INSERT INTO employees VALUES (3, '鈴木一郎', '営業部', 550000);
INSERT INTO employees VALUES (4, '高橋美代', '開発部', 650000);
COMMIT;

-- データ確認
SELECT * FROM employees;
EXIT;" | sql mcp_user/mcp_password@localhost:1521/freepdb1

🚀 Step 2: SQLcl 25.2のインストールと設定

2.1 Java環境の確認と準備

SQLcl MCPを利用する場合はJava 17以上が必要です：

# Javaバージョン確認
java -version

# Java未インストールまたは古いバージョンの場合
sudo dnf install -y java-17-openjdk java-17-openjdk-devel

# 環境変数設定
echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk' >> ~/.bashrc

期待される出力例:

openjdk version "17.0.16" 2025-07-15 LTS
OpenJDK Runtime Environment (Red_Hat-17.0.16.0.8-2.0.1)
OpenJDK 64-Bit Server VM (Red_Hat-17.0.16.0.8-2.0.1)

2.2 SQLcl 25.2の入手と展開

SQLcl 25.2をダウンロードし､インストールします：

# 最新版SQLclダウンロード（25.2.2.199.0918）
wget -O sqlcl-25.2.2.199.0918.zip \
  https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-25.2.2.199.0918.zip

# 解凍
unzip sqlcl-25.2.2.199.0918.zip
mv sqlcl $ORACLE_HOME/

# バージョン確認
$ORACLE_HOME/sqlcl/bin/sql -version

期待される出力例:

SQLcl: Release 25.2.2.0 Production Build: 25.2.2.199.0918

2.3 SQLcl環境の設定

# パスの設定（既に設定済みの場合はスキップ）
export PATH=$ORACLE_HOME/sqlcl/bin:$PATH
source ~/.bashrc

2.4 SQLcl動作確認とMCP機能の確認

# SQLclのMCP機能確認
sql -help | grep -i mcp

期待される出力:

    -mcp        Run the Model Context Protocol (MCP) Server

# 接続テスト
sql mcp_user/mcp_password@localhost:1521/freepdb1

接続に成功すると以下のようなプロンプトが表示されます：

SQLcl: Release 25.2.2.0 Production Build: 25.2.2.199.0918

Connected to:
Oracle Database 23ai Free Release 23.0.0.0.0

SQL>

⚙️ Step 3: 名前付き接続の作成

MCPサーバーは名前付き接続を使用するため、接続情報を保存します：

3.1 名前付き接続の作成

# 名前付き接続の保存
echo "conn -save mcpconn -savepwd mcp_user/mcp_password@localhost:1521/freepdb1
exit" | sql /nolog

成功時の出力例:

Name: mcpconn
Connect String: localhost:1521/freepdb1
User: mcp_user
Password: ******
Connected.

3.2 保存された接続の確認

# 保存された接続一覧表示
echo "connmgr list
exit" | sql /nolog

期待される出力例:

Available Connections:
├── mcpconn
└── (他の接続があれば表示)

3.3 接続テスト

# 名前付き接続でのテスト
echo "conn -name mcpconn
show user
exit" | sql /nolog

🔧 Step 4: MCP（Model Context Protocol）サーバーの設定

4.1 MCPサーバー起動テスト

SQLcl 25.2の標準MCP機能をテストします：

# MCPサーバーの起動テスト
sql -mcp

# 起動確認できたら止めて良い

期待される出力例:

---------- MCP SERVER STARTUP ----------
MCP Server started successfully on Mon Aug 04 09:04:00 UTC 2025
Press Ctrl+C to stop the server
----------------------------------------

4.2 Claude Code CLI設定

Claude CodeでMCPサーバーを利用するための設定を行います：

設定ファイルの場所確認

# Claude Code設定ディレクトリの確認
ls -la ~/.claude.json

Claude Code設定ファイルの作成

~/.claude.jsonに以下の設定を追加：

# 設定ファイルの作成/更新
cat > ~/.claude.json << 'EOF'
{
  "mcpServers": {
    "sqlcl-oracle": {
      "command": "/opt/oracle/product/23ai/dbhomeFree/sqlcl/bin/sql",
      "args": ["-mcp"],
      "env": {
        "ORACLE_HOME": "/opt/oracle/product/23ai/dbhomeFree",
        "PATH": "/opt/oracle/product/23ai/dbhomeFree/bin:/opt/oracle/product/23ai/dbhomeFree/sqlcl/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
        "ORACLE_SID": "FREE",
        "LD_LIBRARY_PATH": "/opt/oracle/product/23ai/dbhomeFree/lib"
      }
    }
  }
}
EOF

設定の確認

# 設定ファイルの内容確認
cat ~/.claude.json

4.3 Claude Code CLIへのMCPサーバー確認

MCP追加の確認:

# 追加されたMCPサーバーの一覧確認
claude mcp list

期待される出力:

claude mcp list
Checking MCP server health...

sqlcl-oracle: /opt/oracle/product/23ai/dbhomeFree/sqlcl/bin/sql -mcp - ✓ Connected

🎉 Step 5: ClaudeからのMCP接続と使用方法

5.1 Claude Code CLIでのMCPサーバー利用

Claude Code CLIを起動すると、追加したMCPサーバーが自動的に認識されます：

# Claude Code CLI起動（別ターミナルで実行）
claude

起動時のMCPサーバー認識ログ:

Claude Code CLI v1.x.x
✓ Initializing MCP servers...
✓ sqlcl-oracle: Connected successfully
✓ Available tools: list-connections, connect, disconnect, run-sql, run-sqlcl
Ready for interaction.

5.2 基本的なMCPツールの使用方法

SQLcl MCPサーバーでは以下のツールが利用可能です：

5.2.1 接続一覧の取得

「保存された接続の一覧を表示して」

Claudeがlist-connectionsツールを使用して接続一覧を表示します。

5.2.2 データベースへの接続

「mcpconnに接続して」

Claudeがconnectツールを使用してmcpconn接続でデータベースに接続します。

5.2.3 SQLクエリの実行

「employeesテーブルのデータを全て表示して」

Claudeがrun-sqlツールを使用して以下のようなクエリを実行：

SELECT /* LLM in use is claude-sonnet-4 */ * FROM employees;

5.3 実用的な使用例

以下のような自然言語でのデータベース操作が可能になります：

データ検索・分析

「営業部の社員の平均給与を計算して」
「開発部で給与が60万円以上の社員を検索して」
「部署別の社員数と平均給与を表示して」

データ操作

「新しい社員を追加して：山田次郎、マーケティング部、550000円」
「田中太郎の給与を520000円に更新して」
「部署が営業部の社員の給与を5%アップして」

スキーマ情報

「employeesテーブルの構造を教えて」
「このデータベースにあるテーブル一覧を表示して」

5.4 MCPツールの詳細

list-connections

  • 目的: 保存された接続の一覧表示
  • 使用場面: 利用可能な接続を確認したい時

connect

  • 目的: 指定された名前付き接続への接続
  • パラメータ: connection_name (接続名)
  • 使用場面: データベース操作を開始する前

disconnect

  • 目的: 現在の接続を切断
  • 使用場面: 作業終了時やセキュリティ上の理由

run-sql

  • 目的: SQL文の実行
  • パラメータ: sql (実行するSQL文)
  • 戻り値: CSV形式の結果
  • 使用場面: データの検索、更新、分析など

run-sqlcl

  • 目的: SQLcl固有コマンドの実行
  • 使用場面: SQLcl特有の機能を使用する時

🔍 Step 6: トラブルシューティング

6.1 よくあるエラーと対処法

接続エラー（ORA-01017: invalid credential）

# パスワードリセット
echo "conn / as sysdba
alter session set container=freepdb1;
alter user mcp_user identified by mcp_password;
exit" | sql /nolog

テーブルが見つからない（ORA-00942）

# スキーマ確認
echo "conn mcp_user/mcp_password@localhost:1521/freepdb1
select table_name from user_tables;
exit" | sql /nolog

MCPサーバーが認識されない

# 設定ファイル確認
cat ~/.claude.json

# 環境変数確認
env | grep ORACLE

# SQLclパス確認
which sql

6.2 ログとモニタリング

SQLcl MCP操作ログの確認

-- MCP操作ログテーブル（存在する場合）
SELECT * FROM DBTOOLS$MCP_LOG ORDER BY timestamp DESC;

セッション情報の確認

-- 現在のセッション情報
SELECT module, action, username, status 
FROM v$session 
WHERE username = 'MCP_USER';

🛡️ Step 7: セキュリティとベストプラクティス

7.1 セキュリティ設定

最小権限の原則

-- MCP用ユーザーの権限を制限
REVOKE SELECT ANY TABLE FROM mcp_user;
GRANT SELECT ON specific_table TO mcp_user;

接続制限

-- 同時接続数の制限
ALTER PROFILE DEFAULT LIMIT SESSIONS_PER_USER 2;
ALTER USER mcp_user PROFILE DEFAULT;

7.2 運用上のベストプラクティス

  1. 本番環境での注意事項

    • MCPサーバーは開発・テスト環境での使用を推奨
    • 本番環境では読み取り専用ユーザーを使用

  2. 定期的な監査

    • MCP操作ログの定期確認
    • 不審なクエリパターンの監視

  3. バックアップ

    • MCP操作前の重要データバックアップ
    • 接続設定のバックアップ

🎯 Step 8: 応用例と活用シナリオ

8.1 データ分析ワークフロー

1. 「データベースの接続を開始して」
2. 「売上データの月別トレンドを分析して」
3. 「異常値を検出して詳細を表示して」
4. 「結果をCSV形式で出力して」

8.2 定期的なレポート生成

1. 「今月の部署別パフォーマンス報告書を作成して」
2. 「従業員満足度調査の結果を集計して」
3. 「予算vs実績の比較分析を実行して」

8.3 データ品質チェック

1. 「重複データを検出して」
2. 「NULL値の分布を確認して」
3. 「データの整合性をチェックして」

📊 まとめ

SQLcl 25.2の標準MCP機能により、以下が実現できました：

✅ 達成できたこと

  • シームレスなAI-DB統合: 自然言語でのデータベース操作
  • セキュアな接続管理: 名前付き接続による安全な認証
  • 監査可能な操作: すべてのSQL実行にLLM識別コメント付与
  • 柔軟なクエリ実行: 複雑な分析クエリの自動生成

🚀 次のステップ

  1. 高度な分析機能

    • 機械学習モデルとの連携
    • リアルタイムデータ分析
    • 自動化されたレポート生成

  2. エンタープライズ統合

    • CI/CDパイプラインへの組み込み
    • 複数データベースの統合管理
    • ROLEベースアクセス制御

  3. パフォーマンス最適化

    • クエリ最適化の自動化
    • インデックス推奨機能
    • リソース使用量の監視

📚 参考リンク

作成日: 2025-08-04
環境: Oracle Database 23ai Free, SQLcl 25.2, Claude Code CLI
対象読者: データベース管理者、開発者、AIアプリケーション構築者

このガイドを参考に、あなたも次世代のAI-データベース統合を体験してみてください！

1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?