Skip to main content

Rill MCP Server


The Rill Model Context Protocol (MCP) server exposes Rill's most essential APIs to LLMs. It is currently designed primarily for data analysts, not data engineers, and focuses on consuming Rill metrics views—not creating them.

Looking for AI Chat in Rill Cloud?

If you want to chat with your data directly in your browser without any setup, check out AI Chat, which uses the same MCP technology but is built right into Rill Cloud.

Why use MCP with Rill?​

Instead of blindly exposing your entire data warehouse to external platforms in hopes of uncovering trends, Rill's MCP integration provides a structured and governed alternative. By querying data that already has predefined measures and dimensions, the responses you get are guaranteed to be as accurate and consistent as the metrics displayed in your Rill dashboards.

Rill offers two ways to use MCP:

  • Rill MCP Server (this guide) - Connect external AI assistants like Claude Desktop to your Rill projects
  • AI Chat - Built-in chat interface in Rill Cloud with zero setup required

You can also add ai_instructions to your project file and metrics views, which will give your LLM additional context on how to use the Rill MCP Server for best results.

Configure AI instructions

Set project-wide AI instructions to provide context unique to your project and improve MCP responses. Learn more about AI configuration →

Users can then ask questions like:

  • What are my week-on-week increases or decreases in sales of XYZ service?
  • During the current year, do I have any outliers in website views? What might this correlate to?
  • In the previous quarter, compared to the current ongoing quarter, what are the trends for customer access?
  • In the last 7 days, how many auction requests were there from mobile vs desktop?

This ensures trustworthy, governed analytics while empowering users to self-serve answers to everyday business questions—without delays caused by email chains or ticket requests. The result: greater team productivity, clearer data ownership, and faster, more confident decision-making across your organization.

Installation​

Prerequisites​

To use the Rill MCP server, you'll need:

  • An MCP client (we recommend Claude Desktop, but you can use any compatible client. Why?)
  • A running Rill project (locally or hosted on Rill Cloud)

The easiest way to connect your Rill app to Claude Desktop or ChatGPT is through their custom connector interfaces, which handle authentication automatically via OAuth. This eliminates the need to manually create access tokens or edit configuration files.

Claude Desktop (Paid Plan)​

Paid Claude Desktop Required

Custom connectors are only available in the paid plan of Claude Desktop. Learn more about Claude Desktop custom connectors →

  1. Open Claude Desktop and navigate to Settings → Connectors
  2. Click Add custom connector
  3. Enter the Rill MCP URL for your project: 
    https://api.rilldata.com/v1/orgs/{org_name}/projects/{project_name}/runtime/mcp
    Replace {org_name} and {project_name} with your organization and project names.
  4. The OAuth flow will automatically start in your browser
  5. Log in to Rill and authorize the connection
  6. Claude Desktop will receive an access token and your Rill app will be connected

Claude Code (Paid Plan)​

  1. On terminal, run the following command to add mcp server with Claude Code:

    claude mcp add --transport http <rill-mcp-server-name> https://api.rilldata.com/v1/orgs/{org_name}/projects/{project_name}/runtime/mcp

    Replace {org_name} and {project_name} with your organization and project names. <rill-mcp-server-name> will be the name you assign to this MCP server.

  2. Open Claude Code using claude cmd.

  3. In Claude Code, use /mcp command to see the list of MCP servers.

  4. Choose the Rill MCP server you just added.

  5. Select Authenticate to start the OAuth flow in your browser.

  6. Log in to Rill and authorize the connection.

  7. Claude Code will receive an access token, and your Rill app will be connected.

ChatGPT Web Interface (Paid Plan)​

Paid ChatGPT Required

Custom apps with Developer mode are only available in the paid plans of ChatGPT. Learn more about ChatGPT Developer mode →

  1. Open ChatGPT and navigate to Settings → Apps & Connectors → Advanced Settings
  2. Enable Developer mode
  3. Go back to Apps & Connectors and click Create in the Apps section
  4. Enter the Rill MCP URL for your project: 
    https://api.rilldata.com/v1/orgs/{org_name}/projects/{project_name}/runtime/mcp
    Replace {org_name} and {project_name} with your organization and project names.
  5. The OAuth flow will automatically start in your browser
  6. Log in to Rill and authorize the connection
  7. ChatGPT will receive an access token and your Rill app will be connected

Manual Configuration (Alternative Method)​

If you prefer to manually configure the connection or need to connect to a local Rill instance, you can edit configuration files directly and provide your own access token. Note: If you select this option, you must have Node.js installed on your system which can be downloaded from nodejs.org

Create a Rill Personal Access Token (if your project is on Rill Cloud)​

Via UI (recommended):

Navigate to the AI tab in your project to retrieve both the JSON config and create a personal access token automatically:


Via CLI:

# Install the Rill CLI if you haven't already
curl https://rill.sh | sh

# Create a token
rill token issue
Learn more about user tokens

For comprehensive documentation on creating, managing, and using personal access tokens, see User Tokens.

Configure Claude Desktop​

Edit your claude_desktop_config.json file. By default, the JSON file is found in the following directories:

  • macOS: /Users/{USER}/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: C:\Users\{USER}\AppData\Roaming\Claude\claude_desktop_config.json

config.json​

Depending on which Rill instance you are trying to connect to (locally running Rill Developer, public Rill project on Rill Cloud, or private Rill project on Rill Cloud (default)), the configuration will vary. For Rill Cloud deployed projects, you can navigate to the AI page to retrieve the config.json.

Private Rill Project on Rill Cloud

Replace org and project with the ID of your organization and project.

{
    "mcpServers": {
        "rill": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://api.rilldata.com/v1/organizations/{org}/projects/{project}/runtime/mcp",
                "--header",
                "Authorization:${AUTH_HEADER}"
            ],
            "env": {
                "AUTH_HEADER": "Bearer <Rill access token>"
            }
        }
    }
}

Public Rill Project on Rill Cloud

See our demo page for public projects to test.

{
    "mcpServers": {
        "rill": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://api.rilldata.com/v1/organizations/demo/projects/rill-github-analytics/runtime/mcp"
            ]
        }
    }
}

Locally Running Rill Developer

{
    "mcpServers": {
        "rill": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "http://localhost:9009/mcp"
            ]
        }
    }
}
Restart Claude!

Restart Claude Desktop for any changes to your JSON file to take effect.

Troubleshooting​

If Claude Desktop cannot connect to the MCP server, check that Rill is running (locally) or that you are able to connect to your Rill project from your browser. If your project is private, check that the token is valid via the CLI or create a new one in the UI and edit the config.json file.

If you're still experiencing issues, check the logs in Claude Desktop. Click on Developer → Open MCP Log File and check the logs for any errors.

Adding AI instructions to your metrics view or project YAML​

LLMs give their best results when they have good context. For a conversation with Rill Data, this means things like clarifying project-specific terms, routing questions to the correct metrics view, or defining business rules. Rather than expecting the user to provide this context every time, you can add ai_instructions to your model. This adds the context automatically for every conversation.

There are two places to add ai_instructions:

  1. rill.yaml for project-wide context, such as instructions on how to use Rill MCP Server
  2. Every metrics view YAML (<metrics_view>.yaml), with examples of Explore URLs for that metrics view

For detailed examples and best practices on writing effective AI instructions, see the AI Configuration guide.

You can look at one of our example projects to see how these are used. Experiment with the instructions and see what works best for your requirements.

Using Rill MCP Server in Claude​


Supported Actions​

  • List metrics views – Use list_metrics_views to discover available metrics views in the project.
  • Get metrics view spec – Use get_metrics_view to fetch a metrics view's specification. This is important to understand all the dimensions and measures in a metrics view.
  • Query the time range – Use query_metrics_view_summary to obtain the available time range for a metrics view. This is important to understand what time range the data spans.
  • Query the metrics – Use query_metrics_view to run queries to get aggregated results.

Usage Examples​

Using all the above concepts, you can ask the Rill MCP server questions like:

  • What are my week-on-week increases or decreases in sales of XYZ service?
  • During the current year, do I have any outliers in website views? What might this correlate to?
  • In the previous quarter, compared to the current ongoing quarter, what are the trends for customer access?
  • In the last 7 days, how many auction requests were there from mobile vs desktop?

Conclusion​

While Explore dashboards are a great way to slice and dice to find insights, sometimes you just need a quick, overall summary of your data via a text conversation. The Rill MCP server enables this through external AI assistants like Claude Desktop. Since Rill MCP is built on top of your existing metrics, you can be confident that the returned data will be correct.

Want AI chat directly in Rill Cloud? Check out AI Chat for a browser-based experience that uses the same MCP technology with zero setup required.

Need help?​

Contact our team if you have any questions, comments, or concerns!