Databricks Apps上のカスタムMCPサーバー

このプロジェクトは、Databricks Apps上でカスタムMCP (Model Context Protocol) サーバーを構築・デプロイするためのサンプル実装です。LLM（Claude、Cursor等）から呼び出し可能な2つのツールを提供します。

提供するツール

1. get_stock_info: TSE（東京証券取引所）の株式情報を取得
2. run_query_on_databricks: Databricks SQLウェアハウスでSQLクエリを実行

プロジェクト構成

custom_mcp/
├── app.py              # MCPサーバーのメインアプリケーション
├── main.py             # Uvicornサーバーのエントリーポイント
├── app.yaml            # Databricks Apps設定ファイル
├── databricks.yml      # Databricksバンドル設定
├── requirements.txt    # Python依存関係
└── README.md           # このファイル

セットアップ

必要な環境

• Python 3.11以上
• Databricks CLI
• Databricksワークスペースへのアクセス権限

ローカル開発環境のセットアップ

1. 仮想環境の作成と有効化

python3 -m venv .venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate

2. 依存関係のインストール

pip install -r requirements.txt

3. ローカルでサーバーを起動

python main.py

サーバーは http://localhost:8000 で起動します。

4. ヘルスチェック

curl http://localhost:8000/health

Databricks Appsへのデプロイ

前提条件

• Databricks CLIがインストールされていること
• Databricksワークスペースに認証済みであること
• SQLウェアハウスが作成されていること

デプロイ手順

1. app.yamlの設定

app.yamlのWAREHOUSE_ID環境変数に、使用するSQLウェアハウスのIDを設定します。

command: ["python", "main.py"]
env:
  - name: 'WAREHOUSE_ID'
    value: 'your-warehouse-id-here'

2. Databricks Appsにデプロイ

databricks apps deploy

3. デプロイの確認

databricks apps list

デプロイされたアプリのURLを確認します。

LLMクライアントからの利用

Claude Desktop / Cursor の設定例

MCPサーバーの設定ファイル（claude_desktop_config.jsonまたはcursor_config.json）に以下を追加します：

{
  "mcpServers": {
    "databricks-custom-mcp": {
      "url": "https://your-databricks-app-url.com",
      "transport": "http"
    }
  }
}

使用例

LLMに以下のように指示することで、ツールを呼び出せます：

トヨタ自動車（7203）の株価情報を教えてください

SQLクエリ "SELECT * FROM catalog.schema.table LIMIT 10" を実行してください

トラブルシューティング

よくある問題と解決方法

1. ツールが呼び出されない

問題: LLMがMCPサーバーを認識するが、ツールが表示されない

原因:

• @mcp.tool()デコレーターでnameパラメータを指定していた
• MCPアプリのマウントパスが間違っていた（/mcpではなく/にマウント）

解決方法:

# ❌ 間違った方法
@mcp.tool(name="tool_name", description="...")
def my_tool():
    pass

app.mount("/mcp", mcp_app)  # ❌ サブパスにマウント

# ✅ 正しい方法
@mcp.tool()
def my_tool():
    """ツールの説明をdocstringに記載"""
    pass

app.mount("/", mcp_app)  # ✅ ルートパスにマウント

2. FastMCP object has no attribute 'app' エラー

問題: app = mcp.appやapp = mcp.http_app()でエラーが発生

解決方法: FastMCPでは以下の方法でASGIアプリを作成します：

# ✅ 正しい方法
mcp_app = mcp.streamable_http_app()
app = FastAPI(lifespan=lambda _: mcp.session_manager.run())
app.mount("/", mcp_app)

3. ModuleNotFoundError: No module named 'custom_server'

問題: モジュールが見つからないエラー

原因: ディレクトリ構造が複雑すぎた（src/custom_serverのような入れ子構造）

解決方法: フラットなディレクトリ構造にして、main.pyとapp.pyを同じディレクトリに配置

4. DataFrameが返せない

問題: run_query_on_databricksでpandas DataFrameを直接返すとエラー

解決方法: 文字列に変換してから返す

@mcp.tool()
def run_query_on_databricks(sql_query: str):
    # ... クエリ実行 ...
    df = pd.DataFrame(rows, columns=[...])
    return df.to_string()  # ✅ 文字列に変換

5. Uvicornのreloadモードで起動しない

問題: uvicorn.run(reload=True)が動作しない

解決方法: reloadモードでは、アプリオブジェクトを文字列で指定する必要があります：

# ✅ 正しい方法
uvicorn.run(
    "app:app",  # インポートパスを文字列で指定
    host="0.0.0.0",
    port=8000,
    reload=True,
)

開発のヒント

ツールの追加方法

新しいツールを追加する場合は、@mcp.tool()デコレーターを使用します：

@mcp.tool()
def my_custom_tool(param1: str, param2: int) -> str:
    """このツールの説明をここに記載します。

    LLMがツールを選択する際に、この説明を参考にします。
    """
    # ツールの実装
    result = some_operation(param1, param2)
    return str(result)  # 文字列で返すことを推奨

リソースの追加方法

動的なリソースを公開する場合は、@mcp.resource()デコレーターを使用します：

@mcp.resource("data://{resource_id}")
def get_resource(resource_id: str) -> str:
    """動的リソースを取得"""
    return f"Resource content for {resource_id}"

ログの確認

Databricks Appsのログは、Databricks CLIまたはウェブUIから確認できます：

databricks apps logs <app-name>

セキュリティに関する注意事項

1. 認証: Databricks Appsは自動的にBearerトークン認証を提供します
2. 環境変数: 機密情報はapp.yamlのenvセクションで設定し、コードにハードコーディングしないでください
3. SQLインジェクション: SQLクエリを実行するツールでは、必要に応じて入力検証を実装してください

参考リンク

• FastMCP Documentation
• Databricks Apps Documentation
• Model Context Protocol Specification
• 参考実装例

ライセンス

このプロジェクトはサンプル実装です。自由に改変・利用してください。

サポート

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

1. Databricks Appsのログ
2. ローカル環境でのテスト結果
3. MCPクライアント側の設定

---

作成日: 2025-11-06 バージョン: 1.0.0