MCP Server Setup

Connect Claude, ChatGPT, Cursor, and other AI assistants to your metrics and dashboards via the Model Context Protocol.

The Metricly MCP (Model Context Protocol) server allows AI assistants like Claude to interact with your metrics and dashboards directly. This guide covers setup for both Claude.ai and Claude Code.

Overview

The MCP server exposes these capabilities to AI assistants:

Query Tools:

  • list_metrics - Discover available metrics
  • list_dimensions - Discover available dimensions for grouping
  • query_metrics - Execute metric queries with optional visualization suggestions
  • explain_metric - Get metric calculation details

Dashboard Tools:

  • list_dashboards - List accessible dashboards
  • get_dashboard - Get dashboard configuration
  • create_dashboard - Create new dashboards
  • update_dashboard - Update dashboard properties
  • delete_dashboard - Delete dashboards
  • add_widget - Add widgets to dashboards
  • update_widget - Modify existing widgets
  • remove_widget - Remove widgets
  • reorder_widgets - Change widget order

Semantic Layer Tools (Admin):

  • get_manifest_status - View semantic layer status
  • list_semantic_models / get_semantic_model - Explore data models
  • create_metric / update_metric / delete_metric - Manage metrics
  • create_semantic_model / update_semantic_model / delete_semantic_model - Manage models
  • preview_metric - Test metric definitions
  • import_manifest / export_manifest - Bulk import/export

Claude.ai Setup (Production)

For Claude.ai integration, the MCP server runs as a remote HTTP server with Google OAuth authentication.

Prerequisites

  1. A deployed Metricly instance with the MCP server enabled
  2. Your Metricly account with Google OAuth configured

Adding the MCP Server

  1. Open Claude.ai and go to Settings
  2. Navigate to Integrations or MCP Servers
  3. Click Add MCP Server
  4. Enter the server URL: https://metricly.xyz/mcp (or your self-hosted URL)
  5. Click Connect
  6. Complete Google OAuth authentication when prompted
  7. The server should now show as "Connected"

Using Metricly in Claude.ai

Once connected, you can ask Claude questions like:

"What metrics do I have available?"
"Show me revenue by region for last month"
"Create a new dashboard called 'Sales Overview'"
"Add a line chart showing monthly revenue trend to my Sales dashboard"

Claude will use the MCP tools to interact with your Metricly data.

Claude Code Setup (Local Development)

For Claude Code, the MCP server runs locally in stdio mode, using credentials from the CLI.

Prerequisites

  1. Metricly CLI installed and working
  2. Logged in via metricly login
  3. For development: Firebase emulators running (pnpm dev)

Configuration

Add the MCP server to your Claude Code settings.

Project-level (.mcp.json in project root):

{
  "mcpServers": {
    "metricly": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/metricly/backend",
        "python",
        "/path/to/metricly/backend/mcp_stdio.py"
      ]
    }
  }
}

Global (~/.claude/settings.json):

{
  "mcpServers": {
    "metricly": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/metricly/backend",
        "python",
        "mcp_stdio.py"
      ]
    }
  }
}

Development Mode

For local development with Firebase emulators, use dev mode which bypasses authentication:

{
  "mcpServers": {
    "metricly": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/metricly/backend",
        "python",
        "mcp_stdio.py"
      ],
      "env": {
        "FIRESTORE_EMULATOR_HOST": "localhost:8081",
        "METRICLY_DEV_MODE": "1"
      }
    }
  }
}

Dev mode features:

  • Uses a mock user (dev@metricly.xyz) as owner
  • Connects to local Firebase emulators
  • No login required
  • Uses the local-dev organization

Production Mode (CLI Auth)

For production use, ensure you're logged in via CLI first:

metricly login

Then configure without the METRICLY_DEV_MODE env var:

{
  "mcpServers": {
    "metricly": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/metricly/backend",
        "python",
        "mcp_stdio.py"
      ]
    }
  }
}

The server will use credentials from ~/.metricly/credentials.json.

Available MCP Tools

Query Tools

list_metrics

List all metrics available in your organization.

Returns: Array of metrics with name, type, and description.

Example conversation:

User: "What metrics can I query?"
Claude: [calls list_metrics]
"You have 15 metrics available including total_revenue, order_count,
average_order_value, customer_count, and churn_rate..."

list_dimensions

List dimensions available for grouping metrics.

Returns: Array of dimension names.

Example:

User: "What can I group revenue by?"
Claude: [calls list_dimensions]
"You can group by region, customer_segment, product_category,
order_status, payment_method..."

query_metrics

Execute a metric query and get results.

Parameters: | Parameter | Type | Description | |-----------|------|-------------| | params.metrics | string[] | Metric names to query (required) | | params.dimensions | string[] | Dimensions to group by | | params.grain | string | Time grain: day, week, month, quarter, year | | params.start_date | string | Start date (YYYY-MM-DD) | | params.end_date | string | End date (YYYY-MM-DD) | | params.limit | number | Max rows to return | | params.order_by | string | Column to sort by | | suggest_visualization | boolean | Include viz recommendation |

Example:

User: "What was our revenue by region last quarter?"
Claude: [calls query_metrics with metrics=['total_revenue'],
         dimensions=['region'], grain='quarter']
"Here's revenue by region for Q4:
- North America: $2.4M
- Europe: $1.8M
- Asia Pacific: $1.2M

I'd suggest visualizing this as a bar chart for easy comparison."

explain_metric

Get detailed information about how a metric is calculated.

Parameters: | Parameter | Type | Description | |-----------|------|-------------| | metric_name | string | Name of the metric |

Example:

User: "How is average_order_value calculated?"
Claude: [calls explain_metric with metric_name='average_order_value']
"Average order value is a derived metric calculated as:
total_revenue / order_count

It uses the orders semantic model and includes only completed orders."

Dashboard Tools

list_dashboards

List dashboards you can access.

Returns: Array of dashboards with id, title, visibility, owner.

get_dashboard

Get full dashboard configuration including pages, sections, and widgets.

Parameters: | Parameter | Type | Description | |-----------|------|-------------| | dashboard_id | string | Dashboard ID |

create_dashboard

Create a new dashboard.

Parameters: | Parameter | Type | Description | |-----------|------|-------------| | title | string | Dashboard title | | description | string | Optional description | | visibility | string | "private" or "org" |

Example:

User: "Create a dashboard for tracking customer metrics"
Claude: [calls create_dashboard with title='Customer Metrics', visibility='org']
"Done! I've created a new dashboard called 'Customer Metrics'
shared with your organization. The ID is cust-abc123."

add_widget

Add a widget to a dashboard.

Parameters: | Parameter | Type | Description | |-----------|------|-------------| | dashboard_id | string | Dashboard ID | | widget | object | Widget definition | | page_index | number | Page index (default: 0) | | section_index | number | Section index (default: 0) |

Widget definition:

{
  "type": "line_chart",
  "title": "Revenue Trend",
  "query": {
    "metrics": ["total_revenue"],
    "grain": "month"
  },
  "format": {
    "type": "currency",
    "currency": "USD"
  }
}

Example:

User: "Add a revenue trend chart to the Sales dashboard"
Claude: [calls add_widget with appropriate config]
"Added a line chart showing monthly revenue trend to page 1,
section 1 of your Sales dashboard."

update_widget / remove_widget / reorder_widgets

Modify existing widgets. Requires dashboard ownership.

Semantic Layer Tools (Admin)

These tools require admin or owner role.

create_metric / update_metric / delete_metric

Manage metric definitions in your semantic layer.

Example:

User: "Create a metric for new customer count"
Claude: [calls create_metric with definition]
"Created the 'new_customer_count' metric. It counts customers
where is_first_order is true. Would you like me to add this
to a dashboard?"

preview_metric

Test a metric definition before saving.

Parameters: | Parameter | Type | Description | |-----------|------|-------------| | metric_data | object | Metric definition to test | | sample_query | object | Optional query params |

Example:

User: "Test this metric definition before I save it"
Claude: [calls preview_metric]
"The metric definition looks valid. Sample results:
- 2024-01: 145 new customers
- 2024-02: 162 new customers
- 2024-03: 189 new customers"

import_manifest / export_manifest

Bulk import/export your semantic layer configuration.

Example:

User: "Export my semantic layer for backup"
Claude: [calls export_manifest]
"Exported your semantic layer. It contains:
- 15 metrics
- 5 semantic models
- 32 dimensions

Here's the YAML configuration..."

Example Conversations

Exploring data

User: "I'm new to this dataset. What can you tell me about it?"

Claude: Let me explore what's available.
[calls list_metrics]
[calls list_dimensions]

You have access to 15 metrics across 5 semantic models:

Revenue Metrics:
- total_revenue - Sum of all revenue
- average_order_value - Revenue per order
- revenue_growth - Month-over-month growth

Customer Metrics:
- customer_count - Total customers
- new_customers - First-time buyers
- churn_rate - Customer churn percentage

You can slice these by dimensions like:
- region, customer_segment, product_category
- order_date (by day, week, month, quarter)

Would you like me to show you some specific data?

Building a dashboard

User: "Help me create a sales dashboard with key metrics"

Claude: I'll create a comprehensive sales dashboard for you.
[calls create_dashboard]

Created "Sales Dashboard"! Now let me add some key widgets.
[calls add_widget - KPI for revenue]
[calls add_widget - KPI for orders]
[calls add_widget - line chart for trend]
[calls add_widget - bar chart for regions]

Your Sales Dashboard now has:
1. Revenue KPI with month-over-month comparison
2. Order count KPI
3. Monthly revenue trend (line chart)
4. Revenue by region (bar chart)

You can view it at: https://metricly.xyz/app/dashboards/sales-abc123

Analyzing data

User: "Why did revenue drop in March?"

Claude: Let me investigate the March revenue dip.
[calls query_metrics - monthly revenue]
[calls query_metrics - revenue by region for March vs Feb]
[calls query_metrics - revenue by product category]

I found the issue. March revenue was down 15% primarily due to:

1. **North America** dropped 22%
   - This coincides with the supply chain issues reported

2. **Electronics category** was hit hardest (-28%)
   - Likely related to product recalls on March 5th

3. **New customer acquisition** stayed flat
   - The drop was in repeat purchases

Would you like me to create a dashboard to monitor this going forward?

Troubleshooting

"Authentication required" error

For Claude.ai: Re-authenticate via Settings > Integrations

For Claude Code:

metricly login
# Restart Claude Code

Server not connecting (Claude Code)

  1. Check the path in .mcp.json is correct
  2. Verify uv is installed and in PATH
  3. Check Claude Code logs for errors
  4. Try running manually: 
    uv run --project /path/to/backend python mcp_stdio.py

"Permission denied" for admin tools

Admin tools require elevated permissions. Ask your organization owner to grant admin role.

Dev mode not working

Ensure emulators are running:

pnpm dev

And environment variables are set:

{
  "env": {
    "FIRESTORE_EMULATOR_HOST": "localhost:8081",
    "METRICLY_DEV_MODE": "1"
  }
}

Queries returning no data

  1. Check date range - default is last 30 days
  2. Verify metric names with list_metrics
  3. Check dimension names with list_dimensions
  4. Ensure your organization has data loaded

Security Notes

  • OAuth tokens are stored securely in ~/.metricly/
  • MCP server only accesses data for your authenticated organization
  • Admin operations require explicit role assignment
  • All queries are audited in production environments

Related Documentation

CLI Guide

Query metrics from the command line.

Read guide

Getting Started

New to Metricly? Start here.

Read guide