Tailpipe Model Context Protocol (MCP) Server

Unlock the power of AI-driven log analysis with Tailpipe! This Model Context Protocol server seamlessly connects AI assistants like Claude to your cloud and SaaS logs, enabling natural language exploration and analysis of your entire data estate.

Tailpipe MCP bridges AI assistants and your log data, allowing natural language:

• Queries across CloudTrail, Kubernetes, and other cloud service logs
• Security incident investigation and analysis
• Cost and performance insights
• Query development assistance

Works with your local Tailpipe init SQL scripts, providing safe, read-only access to all your cloud and SaaS log data.

Installation

Prerequisites

• Node.js v16 or higher (includes npx)
• Tailpipe installed and configured

Configuration

Add Tailpipe MCP to your AI assistant's configuration file:

{
  "mcpServers": {
    "tailpipe": {
      "command": "npx",
      "args": [
        "-y",
        "@turbot/tailpipe-mcp"
      ]
    }
  }
}

By default, this will use the Tailpipe CLI to discover your init SQL script. Make sure Tailpipe is installed and configured first.

To connect to a specific init SQL script instead, add the path to the args:

{
  "mcpServers": {
    "tailpipe": {
      "command": "npx",
      "args": [
        "-y",
        "@turbot/tailpipe-mcp",
        "/path/to/your/tailpipe_init_YYYYMMDDHHMMSS.sql"
      ]
    }
  }
}

AI Assistant Setup

Assistant	Config File Location	Setup Guide
Claude Desktop	claude_desktop_config.json	Claude Desktop MCP Guide →
Cursor	~/.cursor/mcp.json	Cursor MCP Guide →

Save the configuration file and restart your AI assistant for the changes to take effect.

Prompting Guide

Ask anything about your log data!

Explore your log data:

What tables do we have available in Tailpipe?

Simple, specific questions work well:

Show me all S3 bucket creation events from CloudTrail in the last 24 hours

Generate security reports:

What were my top 10 AWS services by cost last month?

Dive into incident analysis:

Find any IAM users created outside working hours (9am-5pm) in the last week

Get timeline insights:

Give me a timeline of the session where Venu created the IAM access key

Explore potential risks:

Analyze our cloudtrail errors for any specific security risks

Remember to:

• Be specific about the time period you're interested in
• Mention the type of data you want to analyze (CloudTrail events, cost data, etc.)
• Start with simple queries before adding complex conditions
• Use natural language - the LLM will handle the SQL translation
• Be bold and exploratory, it's amazing what the LLM will discover and achieve!

Capabilities

Tools

Database Operations:

• tailpipe_query

  • Run a read-only Tailpipe SQL query using DuckDB syntax
  • Input: sql (string): The SQL query to execute

• tailpipe_connect

  • Initialize or refresh the DuckDB session from a Tailpipe init SQL script
  • Optional input: init_script_path (string): Path to the init SQL script to use. If not provided, refreshes the current connection.

Data Structure Operations:

• tailpipe_partition_list

  • List all available Tailpipe partitions with simple statistics
  • No input parameters required

• tailpipe_partition_show

  • Show details of a specific Tailpipe partition
  • Input: name (string): Name of the partition to show details for

• tailpipe_table_list

  • List all available Tailpipe tables
  • No input parameters required

• tailpipe_table_show

  • Show details of a specific Tailpipe table and its columns
  • Input: name (string): Name of the table to show details for

Plugin Operations:

• tailpipe_plugin_list

  • List all Tailpipe plugins installed on the system
  • No input parameters required

• tailpipe_plugin_show

  • Get details for a specific Tailpipe plugin installation
  • Input: name (string): Name of the plugin to show details for

Source Operations:

• tailpipe_source_list

  • List all Tailpipe sources available on the system
  • No input parameters required

• tailpipe_source_show

  • Get details for a specific Tailpipe source
  • Input: name (string): Name of the source to show details for

Resources

• status
  • Represents the current state of the Tailpipe connection
  • Properties include:
    • Init script path in use
    • Server configuration
    • Runtime environment

This resource enables AI tools to check and verify the connection status to your Tailpipe session.

Development

Clone and Setup

1. Clone the repository and navigate to the directory:

git clone https://github.com/turbot/tailpipe-mcp.git
cd tailpipe-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Testing

To test your local development build with AI tools that support MCP, update your MCP configuration to use the local dist/index.js instead of the npm package. For example:

{
  "mcpServers": {
    "tailpipe": {
      "command": "node",
      "args": [
        "/absolute/path/to/tailpipe-mcp/dist/index.js",
        "/path/to/your/tailpipe_init_YYYYMMDDHHMMSS.sql"
      ]
    }
  }
}

Or, use the MCP Inspector to validate the server implementation:

npx @modelcontextprotocol/inspector dist/index.js

Environment Variables

The following environment variables can be used to configure the MCP server:

• TAILPIPE_MCP_INIT_SCRIPT_PATH: Specify the Tailpipe init SQL script path (alternative to command line argument)
• TAILPIPE_MCP_LOG_LEVEL: Control logging verbosity (default: info)
  • debug: Show all messages (most verbose)
  • info: Show informational, warning, and error messages
  • warn: Show only warning and error messages
  • error: Show only error messages
• TAILPIPE_MCP_MEMORY_MAX_MB: Maximum memory buffer size in megabytes for command execution

Open Source & Contributing

This repository is published under the Apache 2.0 license. Please see our code of conduct. We look forward to collaborating with you!

Tailpipe is a product produced from this open source software, exclusively by Turbot HQ, Inc. It is distributed under our commercial terms. Others are allowed to make their own distribution of the software, but they cannot use any of the Turbot trademarks, cloud services, etc. You can learn more in our Open Source FAQ.

Get Involved

Join #tailpipe on Slack →

Want to help but don't know where to start? Pick up one of the help wanted issues:

• Tailpipe
• Tailpipe MCP