📌Overview

Purpose: To provide a server that facilitates interactions between Tinybird Workspaces and any compatible MCP client.

Overview: The Tinybird MCP server allows users to query Tinybird Data Sources via the Tinybird Query API, retrieve results from existing API endpoints, and push data files. It is designed to work with both Server-Sent Events (SSE) and standard input/output (STDIO) modes, making it versatile for different application needs.

Key Features:

Data Querying: Facilitates querying of Tinybird Data Sources using the Tinybird Query API, enabling dynamic data analysis and retrieval.
HTTP Request Handling: Allows users to get results from existing Tinybird API endpoints through HTTP requests, simplifying the data access process.
Data File Management: Supports pushing data files into the Tinybird Workspace, providing easy integration of new data streams.
SSE and STDIO Modes: Offers flexibility in integration by supporting both SSE for real-time applications and STDIO for traditional command-line interfaces.

Tinybird MCP server

An MCP server to interact with a Tinybird Workspace from any MCP client.

Features

Query Tinybird Data Sources using the Tinybird Query API
Get the result of existing Tinybird API Endpoints with HTTP requests
Push Datafiles

It supports both SSE and STDIO modes.

Usage examples

Bluesky metrics (Claude transcript)
Web analytics starter kit metrics

Setup

Installation

Using MCP package managers

Smithery

To install Tinybird MCP for Claude Desktop automatically via Smithery:

npx @smithery/cli install @tinybirdco/mcp-tinybird --client claude

mcp-get

Install the Tinybird MCP server using mcp-get:

npx @michaellatman/mcp-get@latest install mcp-tinybird

Prerequisites

MCP is still evolving. It is recommended to follow the MCP documentation to get started.

You'll need:

Tinybird Account & Workspace
Claude Desktop
uv client

Configuration

1. Configure Claude Desktop

Create the following file depending on your OS:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Paste this template and replace <TINYBIRD_API_URL> and <TINYBIRD_ADMIN_TOKEN> with your Tinybird API URL and Admin Token:

{
    "mcpServers": {
        "mcp-tinybird": {
            "command": "uvx",
            "args": [
                "mcp-tinybird",
                "stdio"
            ],
            "env": {
                "TB_API_URL": "<TINYBIRD_API_URL>",
                "TB_ADMIN_TOKEN": "<TINYBIRD_ADMIN_TOKEN>"
            }
        }
    }
}

2. Restart Claude Desktop

SSE mode

Alternatively, run the MCP server in SSE mode:

uvx mcp-tinybird sse

Useful for integrating with an MCP client that supports SSE (e.g., a web app).

Prompts

The server provides a single prompt:

tinybird-default: Assumes data is loaded in Tinybird and helps explore it.
- Requires a "topic" argument defining the data topic, e.g. "Bluesky data" or "retail sales".

You can configure additional prompt workflows by creating a prompts Data Source in your workspace with this schema and appending your prompts. The MCP loads prompts on initialization:

SCHEMA >
    `name` String `json:$.name`,
    `description` String `json:$.description`,
    `timestamp` DateTime `json:$.timestamp`,
    `arguments` Array(String) `json:$.arguments[:]`,
    `prompt` String `json:$.prompt`

Tools

The server implements tools to interact with the Tinybird Workspace:

list-data-sources: Lists all Data Sources
list-pipes: Lists all Pipe Endpoints
get-data-source: Gets information and schema of a Data Source
get-pipe: Gets info about a Pipe Endpoint, including nodes and SQL transformation
request-pipe-data: Requests data from a Pipe Endpoint (supports parameters)
run-select-query: Runs a select query over a Data Source
append-insight: Adds a business insight to the memo resource
llms-tinybird-docs: Contains full Tinybird product documentation for context
save-event: Sends an event to a Tinybird Data Source (e.g., save user-generated prompt)
analyze-pipe: Runs ClickHouse explain on a Pipe Endpoint query and suggests optimizations
push-datafile: Creates remote Data Source or Pipe from a local datafile

Development

Config

For local development, add these environment variables to a .env file in the repository root:

TB_API_URL=
TB_ADMIN_TOKEN=

Update Claude Desktop config for local development:

{
  "mcpServers": {
    "mcp-tinybird_local": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/mcp-tinybird",
        "run",
        "mcp-tinybird",
        "stdio"
      ]
    }
  }
}

Published Servers Configuration:

"mcpServers": {
  "mcp-tinybird": {
    "command": "uvx",
    "args": [
      "mcp-tinybird"
    ]
  }
}

Building and Publishing

Sync dependencies and update lockfile:

uv sync

Build package distributions:

uv build

This creates source and wheel distributions in dist/.

Publish to PyPI:

uv publish

You need to set PyPI credentials via environment variables or command flags.

Debugging

Since MCP servers run over stdio, debugging is easier with the MCP Inspector.

Launch the MCP Inspector via npm:

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-tinybird run mcp-tinybird

The Inspector will display a URL for browser debugging.

Monitoring

Monitor the MCP server with any compatible Prometheus client such as Grafana.