Model Context Protocol (MCP) server for OpenTelemetry eBPF Instrumentation (OBI)

Enable AI assistants to deploy, configure, and analyze application observability using OpenTelemetry's zero-code eBPF instrumentation.

• Features
• Quick Start
• Available Tools
• Resources
• Prompts
• Prerequisites
• Documentation
• Testing
• Project Structure
• Contributing
• License

• 6 MCP Tools: Complete OBI lifecycle management through AI assistants
• 3 MCP Resources: Real-time access to configuration, status, and logs
• 1 MCP Prompt: Guided local deployment setup
• Zero-Code Instrumentation via AI: Deploy OBI with natural language commands
• Process Lifecycle Management: Start, stop, and monitor OBI processes
• Configuration Management: Update OBI configuration through AI assistance
• Log Analysis: Query and analyze OBI telemetry output
• Multi-Platform: Works with any MCP-compatible AI client (Claude Desktop, Continue, etc.)
• 99.81% Test Coverage: Comprehensive test suite with 270 tests
• Full TypeScript Support: Type-safe implementation with complete type definitions

# Clone the repository
git clone https://github.com/raibid-labs/obi-mcp.git
cd obi-mcp

# Install dependencies
npm install

# Build the project
npm run build

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

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

Or, after publishing to npm:

{
  "mcpServers": {
    "obi": {
      "command": "npx",
      "args": ["obi-mcp-server"]
    }
  }
}

After updating the configuration, restart Claude Desktop to load the MCP server.

You: "Deploy OBI with default configuration"
Claude: [Uses obi_deploy_local tool to start OBI]

You: "What's the current status of OBI?"
Claude: [Uses obi_get_status tool to check health]

You: "Show me the recent logs"
Claude: [Uses obi_get_logs tool to fetch logs]

The OBI MCP Server provides 6 tools for managing OpenTelemetry eBPF Instrumentation:

Get the current status of the OBI process.

Arguments:

• verbose (boolean, optional): Include detailed process information (CPU, memory, uptime)
  • Default: false

Example usage in Claude:

"What's the status of OBI?"
"Check if OBI is running and show me detailed metrics"
"Is OBI healthy?"

Returns:

=== OBI Status ===
Status: running
PID: 12345
Uptime: 3600s

--- Details ---
CPU Usage: 2.5%
Memory Usage: 150.32 MB
Config Path: /path/to/obi-config.yml

Deploy OBI locally in standalone mode.

Arguments:

• config (object, optional): OBI configuration object
• configPath (string, optional): Path to OBI configuration file
• binaryPath (string, optional): Path to OBI binary (uses PATH if not provided)

Note: Either config or configPath should be provided.

Example usage in Claude:

"Deploy OBI with default configuration"
"Start OBI using the config at /etc/obi/config.yaml"
"Deploy OBI with network monitoring enabled"

Returns:

=== OBI Local Deployment ===

Status: SUCCESS
Message: OBI deployed successfully
PID: 12345
Config Path: /tmp/obi-config.yaml

Retrieve the current OBI configuration.

Arguments: None

Example usage in Claude:

"Show me the current OBI configuration"
"What's the active configuration?"
"Get OBI config"

Returns:

=== OBI Configuration ===

{
  "network": {
    "enable": true,
    "allowed_attributes": ["http.method", "http.status_code"]
  },
  "export": {
    "otlp": {
      "endpoint": "localhost:4317",
      "protocol": "grpc"
    }
  }
}

Update the OBI configuration with validation.

Arguments:

• config (object, required): New configuration object (or partial config if merge=true)
  • network (object, optional): Network instrumentation settings
    • enable (boolean): Enable network monitoring
    • allowed_attributes (string[]): Allowed HTTP attributes
    • cidrs (array): CIDR configurations
  • attributes (object, optional): Attribute settings
    • kubernetes.enable (boolean): Enable Kubernetes attributes
  • export (object, optional): Export configuration
    • otlp.endpoint (string): OTLP endpoint URL
    • otlp.protocol (string): Protocol (grpc or http/protobuf)
• merge (boolean, optional): Merge with existing config (default: true)
• restart (boolean, optional): Restart OBI after updating (default: false)

Example usage in Claude:

"Update the OTLP endpoint to localhost:4318"
"Enable Kubernetes attributes in the config"
"Change the configuration and restart OBI"

Returns:

=== OBI Config Update ===

Status: Success
Message: Configuration updated successfully

Note: Restart OBI for changes to take effect.

--- Updated Configuration ---
{...}

Retrieve recent logs from the OBI process.

Arguments:

• lines (number, optional): Number of recent log lines to retrieve
  • Default: 100
  • Range: 1-10000
• level (string, optional): Filter logs by level
  • Options: info, warn, error, debug, all

Example usage in Claude:

"Show me the last 50 lines of OBI logs"
"Get error logs from OBI"
"Show recent debug logs"

Returns:

=== OBI Logs === [Level: ERROR] [Last 5 lines]

[2025-11-14 10:23:45] [ERROR] Failed to connect to OTLP endpoint
[2025-11-14 10:23:46] [ERROR] Retrying connection...
[2025-11-14 10:24:00] [ERROR] Connection timeout

--- End of Logs ---

Stop the running OBI process.

Arguments:

• force (boolean, optional): Force immediate termination using SIGKILL
  • Default: false (uses graceful SIGTERM)

Example usage in Claude:

"Stop OBI"
"Shut down the OBI process"
"Force stop OBI immediately"

Returns:

=== OBI Stop ===

Status: Success
Message: OBI process stopped successfully

The OBI process has been stopped successfully.

MCP resources provide read-only access to OBI state and configuration. These can be used by AI assistants to get real-time information.

Name: Current OBI Configuration MIME Type: application/json Description: The current OBI configuration in JSON format

Usage in Claude:

"Read the current OBI configuration resource"

Returns: Current configuration as JSON

Name: OBI Process Health MIME Type: application/json Description: Current health status and metrics of the OBI process

Usage in Claude:

"Check the OBI health resource"
"Show me the health status"

Returns:

{
  "status": "running",
  "running": true,
  "pid": 12345,
  "uptimeSeconds": 3600,
  "cpuUsagePercent": 2.5,
  "memoryUsageMB": 150.32,
  "configPath": "/tmp/obi-config.yaml",
  "timestamp": "2025-11-14T10:30:00.000Z"
}

Name: Recent OBI Logs MIME Type: text/plain Description: Last 100 lines from OBI logs

Usage in Claude:

"Read the recent logs resource"

Returns: Plain text log entries (last 100 lines)

MCP prompts provide guided workflows for common tasks.

Name: Setup OBI Local Deployment Description: Guided setup for deploying OBI (OpenTelemetry eBPF Instrumentation) locally

Arguments:

• environment (string, optional): Target environment type
  • Options: development, production
  • Default: development

Usage in Claude:

"Use the setup-obi-local prompt"
"Guide me through setting up OBI for production"

Provides:

• Prerequisites check (kernel version, sudo access, dependencies)
• Configuration file templates
• Deployment options (binary, Docker, from source)
• Verification steps
• Troubleshooting guide
• Production checklist (when environment=production)

• Node.js >= 18.0.0
• Linux kernel 5.8+ (for OBI eBPF support)
• OBI binary installed (installation guide)
• Root/sudo access (required by OBI for eBPF operations)

• Docker (for containerized deployments)
• bpftool (for debugging eBPF programs)
• OpenTelemetry Collector (for receiving telemetry data)

• API Reference - Complete tool, resource, and prompt specifications
• Architecture - System design and components
• Quick Start Guide - Getting started guide
• Semantic Versioning - Commit messages and versioning
• Release Process - How to create releases
• Roadmap - Future features and timeline
• Changelog - Version history and release notes

The project has comprehensive test coverage with 270 tests and 99.81% coverage.

# Run all tests
npm test

# Run with coverage report
npm test -- --coverage

# Run unit tests only
npm run test:unit

# Run integration tests (requires OBI binary)
npm run test:integration

# Run E2E tests
npm run test:e2e

# Watch mode
npm run test -- --watch

• Unit Tests: Tool handlers, resource handlers, utilities
• Integration Tests: MCP protocol integration, OBI manager
• E2E Tests: Complete lifecycle workflows

obi-mcp-server/
├── src/
│   ├── index.ts              # Entry point
│   ├── server/
│   │   └── index.ts          # MCP server implementation
│   ├── tools/                # MCP tools (6 tools)
│   │   ├── index.ts          # Tool exports
│   │   ├── status.ts         # obi_get_status
│   │   ├── deploy-local.ts   # obi_deploy_local
│   │   ├── get-config.ts     # obi_get_config
│   │   ├── update-config.ts  # obi_update_config
│   │   ├── get-logs.ts       # obi_get_logs
│   │   └── stop.ts           # obi_stop
│   ├── resources/            # MCP resources (3 resources)
│   │   └── index.ts          # Resource handlers
│   ├── prompts/              # MCP prompts (1 prompt)
│   │   ├── index.ts          # Prompt exports
│   │   └── setup-local.ts    # setup-obi-local prompt
│   ├── types/
│   │   ├── obi.ts            # OBI type definitions
│   │   └── mcp.ts            # MCP type definitions
│   └── utils/
│       ├── logger.ts         # Logging utility
│       ├── process.ts        # Process management
│       └── obi-manager.ts    # OBI lifecycle manager
├── tests/
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   └── e2e/                  # End-to-end tests
├── docs/
│   ├── API.md               # API reference
│   ├── ARCHITECTURE.md      # Architecture documentation
│   ├── QUICKSTART.md        # Quick start guide
│   ├── SEMANTIC_VERSIONING.md  # Commit message guide
│   ├── RELEASING.md         # Release process
│   ├── RELEASE_QUICKSTART.md   # Quick release reference
│   └── ROADMAP.md           # Feature roadmap
├── examples/
│   └── configs/             # Example configurations
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

• TypeScript project structure
• MCP server with stdio transport
• 6 MCP tools for OBI management
• 3 MCP resources for config/status/logs
• 1 MCP prompt for guided setup
• Comprehensive test suite (270 tests, 99.81% coverage)
• Complete documentation
• Full TypeScript support

• Docker deployment support
• Basic Kubernetes integration
• Metrics aggregation and analysis
• OTLP endpoint integration
• Configuration validation tool
• Performance benchmarking

• Multi-instance OBI management
• Advanced filtering and querying
• Custom instrumentation targets
• Integration with observability platforms
• Real-time metrics streaming
• Dashboard generation

See ROADMAP.md for detailed timeline and feature specifications.

Contributions are welcome! Please see CONTRIBUTING.md for detailed guidelines.

# Install dependencies
npm install

# Watch TypeScript compilation
npm run watch

# Run in development mode
npm run dev

# Run linter
npm run lint

# Format code
npm run format

# Type check
npm run typecheck

# Run all quality checks
npm run lint && npm run typecheck && npm run test:all && npm run build

We follow Conventional Commits for automatic versioning and changelog generation.

Format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Common types:

Examples:

# New feature
git commit -m "feat(tools): add Kubernetes deployment support"

# Bug fix
git commit -m "fix(status): prevent crash when OBI is not running"

# Breaking change
git commit -m "feat(config)!: restructure configuration schema

BREAKING CHANGE: Config format has changed. See migration guide."

# Documentation
git commit -m "docs(readme): add troubleshooting section"

See detailed guide: docs/SEMANTIC_VERSIONING.md

Releases are automated through conventional commits:

# Create release (choose based on your changes)
npm run release         # PATCH: 0.1.0 → 0.1.1 (bug fixes)
npm run release:minor   # MINOR: 0.1.0 → 0.2.0 (new features)
npm run release:major   # MAJOR: 0.1.0 → 1.0.0 (breaking changes)

# Or use just
just release
just release-minor
just release-major

See: docs/RELEASE_QUICKSTART.md for quick reference

MIT License - see LICENSE for details.

• OpenTelemetry Community for OBI
• Anthropic for Model Context Protocol
• Grafana Labs for Beyla (OBI's predecessor)

• OBI Documentation
• MCP Specification
• MCP TypeScript SDK
• GitHub Issues

• GitHub Issues: Report bugs or request features
• Slack: #otel-ebpf-instrumentation on CNCF Slack
• Discussions: GitHub Discussions

Status: 🚀 Beta - Ready for Testing

Version: 0.1.0 - Initial MVP release with 6 tools, 3 resources, and 1 prompt. Production-ready for evaluation and testing.

If you have just installed, you can use convenient shortcuts:

# Full setup from scratch
just setup

# Start development server
just dev

# Run all tests
just test

# Run tests with coverage
just test-coverage

# Build project
just build

# Run quality checks (typecheck + lint + test)
just check

# Show all available commands
just --list

# Interactive demo
just demo

# Get Claude Desktop setup instructions
just setup-claude

You: "Deploy OBI with default configuration"
Claude: ✓ Deployed OBI successfully (PID: 12345)

You: "What's the status? Show me detailed metrics"
Claude: [Shows CPU: 2.5%, Memory: 150MB, Uptime: 30s]

You: "Show me the last 50 log lines"
Claude: [Displays recent OBI logs]

You: "Show me the current OBI configuration"
Claude: [Displays config JSON]

You: "Update the configuration to enable Kubernetes attributes and restart OBI"
Claude: ✓ Configuration updated and OBI restarted

You: "Verify the new configuration is active"
Claude: [Shows updated config with Kubernetes enabled]

You: "What resources does the OBI server provide?"
Claude: Three resources available:
  • obi://config/current - Current configuration
  • obi://status/health - Health metrics
  • obi://logs/recent - Recent logs

You: "Show me obi://status/health"
Claude: [Displays real-time health data]

You: "Help me set up OBI locally"
Claude: [Launches setup-obi-local prompt with step-by-step guide]

You: "OBI isn't starting - what should I check?"
Claude: Let me help debug:
1. Checking if OBI is already running... ✓ Not running
2. Checking prerequisites...
3. Attempting to deploy with verbose logging...

You: "Show me error logs from the last hour"
Claude: [Filters and displays error-level logs]