The Sidemantic MCP (Model Context Protocol) server enables AI assistants like Claude to query your semantic layer directly.

## What is MCP?

[Model Context Protocol](https://modelcontextprotocol.io) is a standard for connecting AI assistants to external tools and data sources. The Sidemantic MCP server exposes your semantic layer as a set of tools that AI assistants can use.

## Quick Start

### 1. Configure Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json doc-validate=lint
{
  "mcpServers": {
    "sidemantic": {
      "command": "uvx",
      "args": ["sidemantic", "mcp-serve", "./path/to/models"]
    }
  }
}
```

With database:

```json doc-validate=lint
{
  "mcpServers": {
    "sidemantic": {
      "command": "uvx",
      "args": ["sidemantic", "mcp-serve", "./path/to/models", "--db", "data/warehouse.db"]
    }
  }
}
```

**Tip:** Using `uvx` automatically manages the sidemantic installation - no need to install anything manually!

### 2. Test Locally (Optional)

```bash doc-validate=lint
# Try the demo
uvx sidemantic mcp-serve --demo

# Serve your models
uvx sidemantic mcp-serve ./models

# With a DuckDB database
uvx sidemantic mcp-serve ./models --db data/warehouse.db
```

```bash doc-test
uvx sidemantic mcp-serve --help
```

```text doc-expected-contains
Usage: sidemantic mcp-serve
```

### 3. Restart and Query

Restart Claude Desktop and try:

> "List all available models in my semantic layer"

> "Show me the dimensions and metrics for the orders model"

> "Query total revenue by month from the orders model"

## Available Tools

The MCP server provides four tools:

### `list_models`

Lists all models in your semantic layer with basic information.

**Returns:**
- Model name
- Source table
- List of dimension names
- List of metric names
- Relationship count

**Example:**
> "What models are available?"

### `get_models`

Get detailed information about specific models.

**Parameters:**
- `model_names`: List of model names to retrieve

**Returns:**
- Full dimension details (type, SQL, description)
- Full metric details (aggregation, SQL, filters, description)
- Relationship details (type, foreign_key, primary_key, through keys when present)
- Join condition string when it can be derived
- Source metadata (format, file)

**Example:**
> "Show me all the dimensions and metrics for the orders and customers models"

### `run_query`

Execute queries against the semantic layer.

**Parameters:**
- `dimensions`: List of dimension references (e.g., `["orders.customer_name", "orders.created_at__month"]`)
- `metrics`: List of metric references (e.g., `["orders.total_revenue", "orders.order_count"]`)
- `where`: Optional WHERE clause filter
- `order_by`: List of fields to order by
- `limit`: Optional row limit

**Returns:**
- Generated SQL
- Result rows
- Row count

**Examples:**

> "Query total revenue grouped by customer region"

> "Show me monthly revenue for 2024, ordered by month descending"

> "Get the top 10 customers by revenue where order status is completed"

### `create_chart`

Generate a chart from a semantic layer query.

**Parameters:**
- `dimensions`: List of dimension references (e.g., `["orders.created_at__month"]`)
- `metrics`: List of metric references (e.g., `["orders.total_revenue"]`)
- `where`: Optional WHERE clause filter
- `order_by`: List of fields to order by
- `limit`: Optional row limit
- `chart_type`: `"auto"`, `"bar"`, `"line"`, `"area"`, `"scatter"`, or `"point"`
- `title`: Optional chart title (auto-generated if omitted)
- `width`: Chart width in pixels (default: 600)
- `height`: Chart height in pixels (default: 400)

**Returns:**
- Generated SQL
- Vega-Lite spec JSON
- Base64-encoded PNG
- Row count

**Examples:**

> "Chart monthly revenue for 2024"

> "Make a bar chart of top 10 products by revenue"

## Query Syntax

### Field References

Always use `model.field_name` format:

```
orders.customer_name
orders.total_revenue
customers.region
```

### Time Granularity

Time dimensions support granularity suffixes:

```
orders.created_at__year
orders.created_at__month
orders.created_at__week
orders.created_at__day
```

Available granularities: `__year`, `__quarter`, `__month`, `__week`, `__day`, `__hour`

### Automatic Joins

Reference fields from multiple models to trigger automatic joins:

```
dimensions: ["customers.region", "products.category"]
metrics: ["orders.total_revenue"]
```

This automatically joins `orders → customers` and `orders → products` based on relationships defined in your models.

### Filters

Use model.field_name in WHERE conditions:

```
where: "orders.status = 'completed' AND orders.amount > 100"
where: "orders.created_at >= '2024-01-01'"
where: "customers.region IN ('US', 'CA')"
```

## Configuration

### Using Environment Variables

You can use environment variables in your Claude Desktop config:

```json doc-validate=lint
{
  "mcpServers": {
    "sidemantic": {
      "command": "uvx",
      "args": ["sidemantic", "mcp-serve", "${HOME}/projects/my-semantic-layer"],
      "env": {
        "DB_PATH": "${HOME}/data/warehouse.db"
      }
    }
  }
}
```

### Multiple Environments

Configure different servers for dev/prod:

```json doc-validate=lint
{
  "mcpServers": {
    "sidemantic-dev": {
      "command": "uvx",
      "args": ["sidemantic", "mcp-serve", "./models", "--db", "dev.db"]
    },
    "sidemantic-prod": {
      "command": "uvx",
      "args": ["sidemantic", "mcp-serve", "./models", "--db", "prod.db"]
    }
  }
}
```

## Example Queries

Here are some example questions you can ask Claude:

**Discovery:**
- "What models are available in my semantic layer?"
- "Show me all dimensions and metrics for the orders model"
- "What are the relationships between models?"

**Simple Aggregations:**
- "Query total revenue by order status"
- "Show me customer count by region"
- "What's the total revenue?"

**Time Series:**
- "Query monthly revenue for 2024"
- "Show me daily active users by week"
- "Get quarterly revenue trends"

**Cross-Model Queries:**
- "Query total revenue by customer region and product category"
- "Show me order count by customer tier and payment method"

**Filtered Queries:**
- "Query revenue for completed orders only"
- "Show me customers from the US with total revenue over $10,000"
- "Get orders placed in the last 30 days grouped by status"

**Top N Queries:**
- "Show me the top 10 customers by revenue"
- "What are the top 5 products by order count?"
- "Get the 20 highest revenue days"

## Troubleshooting

### Server Not Appearing in Claude

1. Check Claude Desktop config location:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. Verify JSON syntax is valid

3. Restart Claude Desktop completely

4. Check Claude Desktop logs for errors

### Command Not Found

Ensure `uvx` is installed:

```bash doc-validate=lint
which uvx
# Should show path to uvx executable
```

If `uvx` is not available, install `uv`:

```bash doc-validate=lint
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Or use `pipx` instead:

```json doc-validate=lint
{
  "mcpServers": {
    "sidemantic": {
      "command": "pipx",
      "args": ["run", "sidemantic", "mcp-serve", "./models"]
    }
  }
}
```

### Models Not Found

Verify the path to your models directory is correct and absolute:

```json doc-validate=lint
{
  "mcpServers": {
    "sidemantic": {
      "command": "sidemantic",
      "args": ["mcp-serve", "/absolute/path/to/models"]
    }
  }
}
```

## Next Steps

- [Models](models) - Define your semantic models
- [Metrics](metrics) - Create metrics and measures
- [Query](query) - Query syntax reference
- [Python API](python-api) - Programmatic usage