SNC Cribl MCP

A Model Context Protocol (MCP) server that provides tools for querying Cribl deployments.

Table of Contents

• What It Does

• Features

• Installation

• Configuration

• Usage

  • Running the MCP Server

  • Available MCP Tools

  • Example Integration with Claude

• Project Structure

• Development

• Authentication

• Contributing

• License

• Support

What It Does

This MCP server connects to Cribl Stream and Edge deployments to retrieve metadata about worker groups, fleets, sources, destinations, pipelines, and routes. It's designed to work with customer-managed (on-premise) Cribl deployments and exposes structured data through MCP tools that can be consumed by AI assistants like Claude.

The server handles authentication with bearer tokens, manages token refresh automatically, and provides a clean JSON interface for exploring your Cribl infrastructure.

Features

• Comprehensive Discovery: List all worker groups (Stream) and fleets (Edge) in your deployment.

• Configuration Retrieval:

  • Retrieve configured sources across all products and groups.

  • Retrieve configured destinations across all products and groups.

  • Retrieve configured pipelines across all products and groups, with full function configuration details.

  • Retrieve configured routes across all products and groups.

  • Retrieve configured event breakers across all products and groups.

  • Retrieve configured lookups across all products and groups.

• Typed Pipeline Models: 41 Pydantic models for pipeline function configurations (eval, mask, sampling, regex_extract, etc.) with full type safety.

• Typed Collector Models: 9 Pydantic models for collector source configurations (S3, REST, database, Splunk, Azure Blob, GCS, filesystem, script, health check) with full type safety.

• Graceful Error Handling: SDK validation errors return structured, user-friendly responses with actionable guidance instead of crashing.

• Robust Authentication: Automatic token management and refresh for customer-managed deployments.

• FastMCP Integration: Built with FastMCP 2.0 for easy integration with Claude and other AI assistants.

• Quality Assurance: Comprehensive unit test coverage with full typing support.

Installation

Prerequisites:

• Python 3.14 or higher

• uv package manager (required)

• Access to a Cribl deployment with valid credentials

Steps:

Configuration

Create a .env file in the project root with your Cribl deployment details:

Configuration Options:

*Either provide CRIBL_USERNAME and CRIBL_PASSWORD, or provide CRIBL_BEARER_TOKEN.

Usage

Running the MCP Server

Start the server directly:

Or using the Python module:

Available MCP Tools

The server exposes seven MCP tools, and also mirrors the same data as MCP resources (e.g., cribl://groups, cribl://sources, cribl://destinations, cribl://pipelines, cribl://routes, cribl://breakers, cribl://lookups):

list_groups

Lists all Stream worker groups and Edge fleets from your Cribl deployment.

• Returns: JSON containing groups organized by product (Stream and Edge), with metadata including group IDs, names, descriptions, and configuration.

list_sources

Lists all configured sources across all groups and products, including both regular sources (from /system/inputs) and collector sources (from /lib/jobs).

• Returns: JSON containing sources organized by product and group, including source IDs, types, and configurations. Collector sources (S3, REST, database, etc.) are merged with regular sources per group.

list_destinations

Lists all configured destinations across all groups and products.

• Returns: JSON containing destinations organized by product and group, including destination IDs, types, and configurations.

list_pipelines

Lists all configured pipelines across all groups and products.

• Returns: JSON containing pipelines organized by product and group, including pipeline IDs, names, and configurations.

list_routes

Lists all configured routes across all groups and products.

• Returns: JSON containing routes organized by product and group, including route IDs, names, filters, destinations, and referenced pipelines.

list_breakers

Lists all configured event breakers across all groups and products.

• Returns: JSON containing event breakers organized by product and group, including ruleset IDs, rules, and configurations.

list_lookups

Lists all configured lookups across all groups and products.

• Returns: JSON containing lookups organized by product and group, including lookup IDs, file info, and configurations.

Example Integration with Claude

Add this server to your Claude desktop app configuration:

Project Structure

Development

Running Tests

Code Quality

Adding a New Tool

1. Create the implementation logic in src/snc_cribl_mcp/operations/.

2. Create a new tool file in src/snc_cribl_mcp/tools/ following the existing pattern.

3. Register the tool in src/snc_cribl_mcp/server.py in the _register_capabilities() function.

4. Add corresponding tests in tests/unit/.

Authentication

This server uses bearer token authentication with the Cribl API. Tokens are retrieved automatically using your username and password, and the server handles token refresh internally.

For customer-managed deployments:

• Tokens expire based on your Cribl settings (default: 1 hour).

• The TokenManager automatically fetches new tokens when needed, using the JWT exp claim when available and falling back to a conservative default.

• For production use, configure TLS and use HTTPS.

See docs/cribl_api_auth.md for detailed authentication documentation.

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository.

2. Create a feature branch (git checkout -b feature/amazing-feature).

3. Make your changes and add tests.

4. Run the test suite (uv run pytest).

5. Run type checking and linting (uv run pyright && uv run ruff check).

6. Commit your changes with a descriptive message.

7. Push to your branch (git push origin feature/amazing-feature).

8. Open a Pull Request.

Please ensure all tests pass and maintain code coverage before submitting a PR.

License

This project is licensed under the MIT No Attribution License (MIT-0). See the LICENSE file for details.

Support

For issues, questions, or feature requests, please open an issue in the repository.