API.mdā¢15.6 kB
# Databricks MCP Server API Documentation
Complete reference for all 60+ tools provided by the Databricks MCP Server.
## Table of Contents
- [Cluster Management Tools](#cluster-management-tools)
- [Notebook Management Tools](#notebook-management-tools)
- [Job Management Tools](#job-management-tools)
- [User & Group Management Tools](#user--group-management-tools)
- [Unity Catalog Tools](#unity-catalog-tools)
- [Permission Tools](#permission-tools)
- [FinOps Tools](#finops-tools)
---
## Cluster Management Tools
### list_clusters
List all clusters in the Databricks workspace.
**Parameters:** None
**Returns:**
```json
{
"total_clusters": 5,
"clusters": [
{
"cluster_id": "0123-456789-abc123",
"cluster_name": "my-cluster",
"state": "RUNNING",
"spark_version": "13.3.x-scala2.12",
"node_type": "i3.xlarge",
"num_workers": 4,
"creator": "user@example.com"
}
]
}
```
**Example:**
```
User: "Show me all clusters"
AI: Uses list_clusters tool
```
---
### get_cluster_details
Get detailed information about a specific cluster.
**Parameters:**
- `cluster_id` (string, required): The unique identifier of the cluster
**Returns:**
```json
{
"cluster_id": "0123-456789-abc123",
"cluster_name": "my-cluster",
"state": "RUNNING",
"spark_version": "13.3.x-scala2.12",
"node_type_id": "i3.xlarge",
"num_workers": 4,
"autoscale": null,
"autotermination_minutes": 120,
"spark_conf": {},
"custom_tags": {"team": "data-engineering"}
}
```
---
### create_cluster
Create a new Databricks cluster.
**Parameters:**
- `cluster_name` (string, required): Name for the cluster
- `spark_version` (string, required): Spark version (e.g., "13.3.x-scala2.12")
- `node_type_id` (string, required): Node type (e.g., "i3.xlarge")
- `driver_node_type_id` (string, optional): Driver node type
- `num_workers` (number, optional): Number of workers (fixed size)
- `autoscale_min_workers` (number, optional): Min workers for autoscaling
- `autoscale_max_workers` (number, optional): Max workers for autoscaling
- `autotermination_minutes` (number, optional): Auto-terminate after N minutes
- `spark_conf` (object, optional): Spark configuration
- `custom_tags` (object, optional): Custom tags
- `enable_elastic_disk` (boolean, optional): Enable elastic disk
- `instance_pool_id` (string, optional): Instance pool to use
- `policy_id` (string, optional): Cluster policy ID
**Returns:**
```json
{
"message": "Cluster creation initiated",
"cluster_id": "0123-456789-abc123",
"cluster_name": "my-new-cluster"
}
```
---
### start_cluster
Start a terminated cluster.
**Parameters:**
- `cluster_id` (string, required): Cluster ID to start
**Returns:**
```json
{
"message": "Cluster start initiated",
"cluster_id": "0123-456789-abc123"
}
```
---
### terminate_cluster
Terminate a running cluster.
**Parameters:**
- `cluster_id` (string, required): Cluster ID to terminate
**Returns:**
```json
{
"message": "Cluster termination initiated",
"cluster_id": "0123-456789-abc123"
}
```
---
## Notebook Management Tools
### list_notebooks
List all notebooks in a workspace path.
**Parameters:**
- `path` (string, required): Workspace path (e.g., "/Users/user@example.com")
**Returns:**
```json
{
"path": "/Users/user@example.com",
"total_objects": 5,
"objects": [
{
"path": "/Users/user@example.com/my-notebook",
"object_type": "NOTEBOOK",
"language": "PYTHON",
"created_at": 1234567890000,
"modified_at": 1234567890000
}
]
}
```
---
### read_notebook
Read the content of a notebook.
**Parameters:**
- `path` (string, required): Full notebook path
- `format` (string, optional): Export format - "SOURCE", "HTML", "JUPYTER", "DBC"
**Returns:**
```json
{
"path": "/Users/user@example.com/my-notebook",
"language": "PYTHON",
"format": "SOURCE",
"content": "# Databricks notebook source\nprint('Hello')"
}
```
---
### create_notebook
Create a new notebook.
**Parameters:**
- `path` (string, required): Full path for new notebook
- `language` (string, optional): "PYTHON", "SCALA", "SQL", "R" (default: "PYTHON")
- `content` (string, optional): Initial content
- `format` (string, optional): Content format
**Returns:**
```json
{
"message": "Notebook created successfully",
"path": "/Users/user@example.com/new-notebook",
"language": "PYTHON"
}
```
---
### run_notebook
Execute a notebook and return results.
**Parameters:**
- `notebook_path` (string, required): Path to notebook
- `cluster_id` (string, required): Cluster to run on
- `base_parameters` (object, optional): Parameters as key-value pairs
- `timeout_seconds` (number, optional): Execution timeout
**Returns:**
```json
{
"run_id": 12345,
"state": {
"life_cycle_state": "TERMINATED",
"result_state": "SUCCESS"
},
"execution_duration": 12000,
"output": {
"result": "Notebook executed successfully"
}
}
```
---
## Job Management Tools
### list_jobs
List all jobs in the workspace.
**Parameters:**
- `limit` (number, optional): Max jobs to return (default: 25)
- `offset` (number, optional): Pagination offset
**Returns:**
```json
{
"total_jobs": 10,
"jobs": [
{
"job_id": 123,
"name": "Daily ETL",
"creator": "user@example.com",
"schedule": {
"quartz_cron_expression": "0 0 2 * * ?",
"timezone_id": "UTC"
},
"tasks_count": 3
}
]
}
```
---
### create_job
Create a new job.
**Parameters:**
- `name` (string, required): Job name
- `cluster_id` (string, optional): Existing cluster ID
- `notebook_path` (string, optional): Notebook to run
- `notebook_parameters` (object, optional): Notebook parameters
- `schedule_cron` (string, optional): Cron expression
- `schedule_timezone` (string, optional): Timezone ID
- `max_concurrent_runs` (number, optional): Max concurrent runs
- `timeout_seconds` (number, optional): Job timeout
- `max_retries` (number, optional): Retry count
- `email_on_success` (array, optional): Success notification emails
- `email_on_failure` (array, optional): Failure notification emails
**Returns:**
```json
{
"message": "Job created successfully",
"job_id": 123,
"name": "My New Job"
}
```
---
### run_job
Trigger a manual job run.
**Parameters:**
- `job_id` (number, required): Job ID to run
- `notebook_parameters` (object, optional): Override parameters
- `jar_parameters` (array, optional): JAR parameters
- `python_parameters` (array, optional): Python parameters
**Returns:**
```json
{
"message": "Job run started",
"run_id": 456,
"job_id": 123
}
```
---
### get_job_run_status
Get status of a job run.
**Parameters:**
- `run_id` (number, required): Run ID to check
**Returns:**
```json
{
"run_id": 456,
"job_id": 123,
"state": {
"life_cycle_state": "RUNNING",
"state_message": "In run"
},
"start_time": 1234567890000,
"run_page_url": "https://..."
}
```
---
## User & Group Management Tools
### list_users
List all users in the workspace.
**Returns:**
```json
{
"total_users": 25,
"users": [
{
"id": "123456",
"userName": "user@example.com",
"displayName": "John Doe",
"active": true,
"groups": ["admins", "data-engineers"]
}
]
}
```
---
### create_user
Add a new user to the workspace.
**Parameters:**
- `userName` (string, required): Username (email)
- `displayName` (string, optional): Display name
- `email` (string, optional): Email address
**Returns:**
```json
{
"message": "User created successfully",
"id": "123456",
"userName": "newuser@example.com"
}
```
---
### create_group
Create a new group.
**Parameters:**
- `displayName` (string, required): Group name
**Returns:**
```json
{
"message": "Group created successfully",
"id": "group-123",
"displayName": "my-new-group"
}
```
---
### add_user_to_group
Add a user to a group.
**Parameters:**
- `group_id` (string, required): Group ID
- `user_id` (string, required): User ID
**Returns:**
```json
{
"message": "User added to group successfully",
"group_id": "group-123",
"user_id": "user-456"
}
```
---
## Unity Catalog Tools
### list_catalogs
List all Unity Catalog catalogs.
**Returns:**
```json
{
"total_catalogs": 3,
"catalogs": [
{
"name": "production",
"comment": "Production data",
"owner": "data-team",
"catalog_type": "MANAGED_CATALOG",
"created_at": 1234567890000
}
]
}
```
---
### list_schemas
List schemas in a catalog.
**Parameters:**
- `catalog_name` (string, required): Catalog name
**Returns:**
```json
{
"catalog_name": "production",
"total_schemas": 5,
"schemas": [
{
"name": "sales",
"full_name": "production.sales",
"owner": "sales-team",
"created_at": 1234567890000
}
]
}
```
---
### list_tables
List tables in a schema.
**Parameters:**
- `catalog_name` (string, required): Catalog name
- `schema_name` (string, required): Schema name
**Returns:**
```json
{
"catalog_name": "production",
"schema_name": "sales",
"total_tables": 12,
"tables": [
{
"name": "customers",
"full_name": "production.sales.customers",
"table_type": "MANAGED",
"data_source_format": "DELTA",
"column_count": 15
}
]
}
```
---
### get_table_details
Get detailed table metadata.
**Parameters:**
- `full_table_name` (string, required): Full table name (catalog.schema.table)
**Returns:**
```json
{
"name": "customers",
"full_name": "production.sales.customers",
"table_type": "MANAGED",
"data_source_format": "DELTA",
"columns": [
{
"name": "customer_id",
"type_text": "bigint",
"position": 0,
"nullable": false
}
],
"owner": "sales-team",
"storage_location": "s3://bucket/path"
}
```
---
### query_table
Execute a SQL query.
**Parameters:**
- `warehouse_id` (string, required): SQL warehouse ID
- `query` (string, required): SQL query
- `catalog` (string, optional): Default catalog
- `schema` (string, optional): Default schema
**Returns:**
Query results in structured format.
---
## Permission Tools
### get_permissions
Get permissions for an object.
**Parameters:**
- `object_type` (string, required): Type - "clusters", "jobs", "notebooks", etc.
- `object_id` (string, required): Object ID
**Returns:**
```json
{
"object_type": "clusters",
"object_id": "0123-456789-abc123",
"access_control_list": [
{
"user_name": "user@example.com",
"permissions": [
{
"permission_level": "CAN_RESTART",
"inherited": false
}
]
}
]
}
```
---
### grant_unity_catalog_permissions
Grant Unity Catalog permissions.
**Parameters:**
- `securable_type` (string, required): "catalog", "schema", "table", etc.
- `securable_name` (string, required): Full object name
- `principal` (string, required): User/group to grant to
- `privileges` (array, required): Privileges to grant
**Returns:**
```json
{
"message": "Unity Catalog permissions granted successfully",
"securable_name": "production.sales.customers",
"principal": "analytics-team",
"privileges": ["SELECT", "USAGE"]
}
```
---
## FinOps Tools
### get_cluster_costs
Analyze cluster costs and usage.
**Parameters:**
- `start_date` (string, required): Start date (YYYY-MM-DD)
- `end_date` (string, required): End date (YYYY-MM-DD)
- `cluster_id` (string, optional): Filter by cluster
**Returns:**
```json
{
"analysis_period": {
"start_date": "2024-01-01",
"end_date": "2024-01-31"
},
"summary": {
"total_clusters": 5,
"total_dbu_consumption": 15000,
"total_estimated_cost_usd": 2250
},
"cluster_metrics": [
{
"cluster_id": "0123-456789-abc123",
"cluster_name": "production-etl",
"uptime_seconds": 86400,
"dbu_consumption": 5000,
"cost_usd": 750
}
]
}
```
---
### analyze_spending_trends
Analyze historical spending trends.
**Parameters:**
- `start_date` (string, required): Start date
- `end_date` (string, required): End date
- `granularity` (string, optional): "daily", "weekly", "monthly"
**Returns:**
```json
{
"analysis_period": {
"start_date": "2024-01-01",
"end_date": "2024-03-31",
"granularity": "weekly"
},
"insights": {
"total_cost": 12450,
"average_cost_per_period": 950,
"peak_cost": 1500,
"lowest_cost": 600
},
"trends": [
{
"date": "2024-01-01",
"cost": 850,
"dbu_usage": 5600,
"cluster_count": 5
}
]
}
```
---
### forecast_costs
Forecast future costs based on historical data.
**Parameters:**
- `historical_days` (number, optional): Days to analyze (default: 30)
- `forecast_days` (number, optional): Days to forecast (default: 30)
**Returns:**
```json
{
"forecast_summary": {
"forecast_days": 30,
"total_predicted_cost": 3200,
"average_daily_cost": 107,
"trend": "increasing"
},
"forecasts": [
{
"forecast_date": "2024-02-01",
"predicted_cost": 105,
"confidence_interval_lower": 84,
"confidence_interval_upper": 126,
"prediction_model": "linear_regression"
}
]
}
```
---
### get_optimization_recommendations
Get cost optimization recommendations.
**Parameters:**
- `min_idle_hours` (number, optional): Min idle hours to flag (default: 24)
**Returns:**
```json
{
"summary": {
"total_recommendations": 8,
"high_severity": 2,
"medium_severity": 4,
"low_severity": 2,
"total_estimated_monthly_savings": 3500
},
"recommendations": [
{
"recommendation_type": "IDLE_CLUSTER",
"severity": "HIGH",
"resource_id": "cluster-123",
"resource_type": "cluster",
"description": "Cluster has been idle for 72 hours",
"estimated_savings_usd": 1200,
"action_items": [
"Terminate the cluster",
"Enable auto-termination"
]
}
]
}
```
---
### analyze_cost_by_tag
Break down costs by custom tags.
**Parameters:**
- `tag_key` (string, required): Tag key to analyze
- `start_date` (string, required): Start date
- `end_date` (string, required): End date
**Returns:**
```json
{
"tag_key": "team",
"summary": {
"total_cost": 12450,
"tag_values_found": 4
},
"breakdown": [
{
"tag_value": "data-engineering",
"cost": 5200,
"dbu_usage": 34500,
"cluster_count": 3,
"percentage_of_total": 42
}
]
}
```
---
## Error Handling
All tools return errors in a consistent format:
```json
{
"error": true,
"message": "Error description",
"tool": "tool_name",
"details": "Additional error details"
}
```
Common error codes:
- **401**: Authentication failed
- **403**: Permission denied
- **404**: Resource not found
- **429**: Rate limit exceeded
- **500**: Server error
---
## Rate Limiting
The server implements automatic rate limiting with exponential backoff:
- Retries automatically on 429 errors
- Waits progressively longer between retries
- Maximum retry delay: 32 seconds
---
## Best Practices
1. **Use specific queries**: More specific tool calls are faster and more accurate
2. **Chain operations**: Let the AI handle multiple steps
3. **Check permissions**: Verify access before attempting operations
4. **Monitor costs**: Use FinOps tools regularly
5. **Tag resources**: Use custom tags for better cost tracking
---
## Additional Resources
- [README](./README.md) - General information and setup
- [CONFIGURATION](./CONFIGURATION.md) - Configuration guide
- [EXAMPLES](./EXAMPLES.md) - Usage examples
- [Databricks API Docs](https://docs.databricks.com/api)