# 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. **仮想環境の作成と有効化**
```bash
python3 -m venv .venv
source .venv/bin/activate # Windowsの場合: .venv\Scripts\activate
```
2. **依存関係のインストール**
```bash
pip install -r requirements.txt
```
3. **ローカルでサーバーを起動**
```bash
python main.py
```
サーバーは `http://localhost:8000` で起動します。
4. **ヘルスチェック**
```bash
curl http://localhost:8000/health
```
## Databricks Appsへのデプロイ
### 前提条件
- Databricks CLIがインストールされていること
- Databricksワークスペースに認証済みであること
- SQLウェアハウスが作成されていること
### デプロイ手順
1. **app.yamlの設定**
`app.yaml`の`WAREHOUSE_ID`環境変数に、使用するSQLウェアハウスのIDを設定します。
```yaml
command: ["python", "main.py"]
env:
- name: 'WAREHOUSE_ID'
value: 'your-warehouse-id-here'
```
2. **Databricks Appsにデプロイ**
```bash
databricks apps deploy
```
3. **デプロイの確認**
```bash
databricks apps list
```
デプロイされたアプリのURLを確認します。
## LLMクライアントからの利用
### Claude Desktop / Cursor の設定例
MCPサーバーの設定ファイル（`claude_desktop_config.json`または`cursor_config.json`）に以下を追加します：
```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`ではなく`/`にマウント）
**解決方法**:
```python
# ❌ 間違った方法
@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アプリを作成します：
```python
# ✅ 正しい方法
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を直接返すとエラー
**解決方法**: 文字列に変換してから返す
```python
@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モードでは、アプリオブジェクトを文字列で指定する必要があります：
```python
# ✅ 正しい方法
uvicorn.run(
"app:app", # インポートパスを文字列で指定
host="0.0.0.0",
port=8000,
reload=True,
)
```
## 開発のヒント
### ツールの追加方法
新しいツールを追加する場合は、`@mcp.tool()`デコレーターを使用します：
```python
@mcp.tool()
def my_custom_tool(param1: str, param2: int) -> str:
"""このツールの説明をここに記載します。
LLMがツールを選択する際に、この説明を参考にします。
"""
# ツールの実装
result = some_operation(param1, param2)
return str(result) # 文字列で返すことを推奨
```
### リソースの追加方法
動的なリソースを公開する場合は、`@mcp.resource()`デコレーターを使用します：
```python
@mcp.resource("data://{resource_id}")
def get_resource(resource_id: str) -> str:
"""動的リソースを取得"""
return f"Resource content for {resource_id}"
```
### ログの確認
Databricks Appsのログは、Databricks CLIまたはウェブUIから確認できます：
```bash
databricks apps logs <app-name>
```
## セキュリティに関する注意事項
1. **認証**: Databricks Appsは自動的にBearerトークン認証を提供します
2. **環境変数**: 機密情報は`app.yaml`の`env`セクションで設定し、コードにハードコーディングしないでください
3. **SQLインジェクション**: SQLクエリを実行するツールでは、必要に応じて入力検証を実装してください
## 参考リンク
- [FastMCP Documentation](https://gofastmcp.com/)
- [Databricks Apps Documentation](https://docs.databricks.com/apps/index.html)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [参考実装例](https://github.com/databrickslabs/mcp/tree/master/examples/custom-server)
## ライセンス
このプロジェクトはサンプル実装です。自由に改変・利用してください。
## サポート
問題が発生した場合は、以下を確認してください：
1. Databricks Appsのログ
2. ローカル環境でのテスト結果
3. MCPクライアント側の設定
---
**作成日**: 2025-11-06
**バージョン**: 1.0.0
