Tailpipe Model Context Protocol (MCP) Server

Created By

turbot10 months ago

Enable AI assistants to explore and query your Tailpipe data!

Content

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 database files, 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 database. Make sure Tailpipe is installed and configured first.

To connect to a specific database file instead, add the path to the args:

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

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

First, run the best_practices prompt included in the MCP server to teach your LLM how best to work with Tailpipe. Then, ask anything!

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
- Refresh the Tailpipe database connection to get the latest data, or connect to a different database path
- Optional input: database_path (string): Database path to connect to. 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

Prompts

best_practices
- Best practices for working with Tailpipe data
- Provides guidance on:
  - Using tools to explore available data (tailpipe_table_list, tailpipe_table_show, etc.)
  - SQL syntax and style conventions
  - Data freshness and connection management
  - Example workflow and queries

Resources

status
- Represents the current state of the Tailpipe connection
- Properties include:
  - Connected database path
  - Server configuration
  - Runtime environment

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

Development

Clone and Setup

Clone the repository and navigate to the directory:

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

Install dependencies:

npm install

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.db"
      ]
    }
  }
}

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_DATABASE_PATH: Specify the database 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.