Databricks Apps上のカスタムMCPサーバー
このプロジェクトは、Databricks Apps上でカスタムMCP (Model Context Protocol) サーバーを構築・デプロイするためのサンプル実装です。LLM（Claude、Cursor等）から呼び出し可能な2つのツールを提供します。
提供するツール
- get_stock_info: TSE（東京証券取引所）の株式情報を取得
- 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ワークスペースへのアクセス権限
ローカル開発環境のセットアップ
- 仮想環境の作成と有効化
python3 -m venv .venv
source .venv/bin/activate # Windowsの場合: .venv\Scripts\activate
- 依存関係のインストール
pip install -r requirements.txt
- ローカルでサーバーを起動
python main.py
サーバーは http://localhost:8000 で起動します。
- ヘルスチェック
curl http://localhost:8000/health
Databricks Appsへのデプロイ
前提条件
- Databricks CLIがインストールされていること
- Databricksワークスペースに認証済みであること
- SQLウェアハウスが作成されていること
デプロイ手順
- app.yamlの設定
app.yamlのWAREHOUSE_ID環境変数に、使用するSQLウェアハウスのIDを設定します。
command: ["python", "main.py"]
env:
- name: 'WAREHOUSE_ID'
value: 'your-warehouse-id-here'
- Databricks Appsにデプロイ
databricks apps deploy
- デプロイの確認
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>
セキュリティに関する注意事項
- 認証: Databricks Appsは自動的にBearerトークン認証を提供します
- 環境変数: 機密情報は
app.yamlのenvセクションで設定し、コードにハードコーディングしないでください - SQLインジェクション: SQLクエリを実行するツールでは、必要に応じて入力検証を実装してください
参考リンク
ライセンス
このプロジェクトはサンプル実装です。自由に改変・利用してください。
サポート
問題が発生した場合は、以下を確認してください：
- Databricks Appsのログ
- ローカル環境でのテスト結果
- MCPクライアント側の設定
作成日: 2025-11-06 バージョン: 1.0.0