Content
# Observability MCP Server
<p align="center">
<a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a>
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://github.com/jlowin/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.3+-7c5cfc?style=flat-square" alt="FastMCP"></a>
</p>
> 📖 **[Installation Guide](INSTALL.md)** · **[PRD](docs/PRD.md)** · **[Changelog](CHANGELOG.md)** · **[FastMCP status](docs/FASTMCP_STATUS.md)**
**FastMCP 3.3+ control plane for unified fleet monitoring (Grafana / Prometheus / Loki on port 12000)**
[](https://github.com/jlowin/fastmcp)
[](https://opentelemetry.io)
[](https://prometheus.io)
[](https://grafana.com)
[](https://grafana.com/oss/loki/)
[](https://github.com/sandraschi/observability-mcp)
MCP + web UI for the **unified** observability stack in `mcp-central-docs/monitoring` (host **12000–12006**). Agents get Grafana/Loki/Prometheus tools; humans get a **Charts** dashboard picker at **:12008** that explains boards in plain language. See [MONITORING_CURRENT_SETUP](https://github.com/sandraschi/mcp-central-docs/blob/main/monitoring/MONITORING_CURRENT_SETUP.md).
---
## Quick Start
```powershell
git clone https://github.com/sandraschi/observability-mcp
cd observability-mcp
just
```
This opens an interactive dashboard showing all available commands. Run `just bootstrap` to install dependencies, then `just serve` or `just dev` to start.
### Manual Setup
If you don't have `just` installed:
## Features
### **FastMCP 3.3+ Integration**
- **OpenTelemetry Integration** - Distributed tracing and metrics collection
- **Enhanced Storage Backend** - Persistent metrics and historical data
- **Production-Ready** - Built for high-performance monitoring
### **Comprehensive Monitoring**
- **Real-time Health Checks** - Monitor MCP server availability and response times
- **Performance Metrics** - CPU, memory, disk, and network monitoring with Prometheus
- **Distributed Tracing** - Track interactions across MCP server ecosystems
- **Centralized Logging** - Loki-powered log aggregation and querying
- **Intelligent Alerting** - Anomaly detection and automated alerts
- **Performance Reports** - Automated analysis and optimization recommendations
### **Advanced Analytics**
- **Usage Pattern Analysis** - Understand how MCP servers are being used
- **Trend Detection** - Identify performance trends and bottlenecks
- **Log Correlation** - Correlate metrics with Loki logs for root cause analysis
- **Optimization Insights** - Data-driven recommendations for improvement
- **Multi-Format Export** - Prometheus, Loki, OpenTelemetry, and JSON export
---
## Installation
### Prerequisites
- [uv](https://docs.astral.sh/uv/) installed (RECOMMENDED)
- Python 3.12+
### Quick Start
Run immediately via `uvx`:
```bash
uvx observability-mcp
```
### Claude Desktop Integration
Add to your `claude_desktop_config.json`:
```json
"mcpServers": {
"observability-mcp": {
"command": "uv",
"args": ["--directory", "D:/Dev/repos/observability-mcp", "run", "observability-mcp"]
}
}
```
### Prerequisites
- Python 3.11+
- FastMCP 3.3++ (automatically installed)
### Install from Source
```bash
git clone https://github.com/sandraschi/observability-mcp
cd observability-mcp
uv pip install -e .
```
## Installation
### Prerequisites
- [uv](https://docs.astral.sh/uv/) installed (RECOMMENDED)
- Python 3.12+
### Quick Start
Run immediately via `uvx`:
```bash
uvx observability-mcp
```
### Claude Desktop Integration
Add to your `claude_desktop_config.json`:
```json
"mcpServers": {
"observability-mcp": {
"command": "uv",
"args": ["--directory", "D:/Dev/repos/observability-mcp", "run", "observability-mcp"]
}
}
```
## Quick Start
### 1. Start the Server
```bash
# Using the CLI
observability-mcp run
# Or directly with Python
python -m observability_mcp.server
```
## Installation
### Prerequisites
- [uv](https://docs.astral.sh/uv/) installed (RECOMMENDED)
- Python 3.12+
### Quick Start
Run immediately via `uvx`:
```bash
uvx observability-mcp
```
### Claude Desktop Integration
Add to your `claude_desktop_config.json`:
```json
"mcpServers": {
"observability-mcp": {
"command": "uv",
"args": ["--directory", "D:/Dev/repos/observability-mcp", "run", "observability-mcp"]
}
}
```
### 3. Configure Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"observability": {
"command": "observability-mcp",
"args": ["run"]
}
}
}
```
---
## Available Tools
### Health Monitoring
- **`monitor_server_health`** - Real-time health checks with OpenTelemetry metrics
- **`monitor_system_resources`** - Comprehensive system resource monitoring
### Performance Analysis
- **`collect_performance_metrics`** - CPU, memory, disk, and network metrics
- **`generate_performance_reports`** - Automated performance analysis and recommendations
- **`analyze_mcp_interactions`** - Usage pattern analysis and optimization insights
### Log Management & Loki Integration
- **`send_logs_to_loki`** - Send custom log entries to Loki for centralized aggregation
- **`query_loki_logs`** - Query logs from Loki with advanced LogQL filtering
- **`analyze_log_patterns`** - Analyze log patterns, anomalies, and trends
- **`correlate_logs_and_metrics`** - Correlate Loki logs with Prometheus metrics
### Alerting & Anomaly Detection
- **`alert_on_anomalies`** - Intelligent anomaly detection and alerting
- **`trace_mcp_calls`** - Distributed tracing for MCP server interactions
### Data Export
- **`export_metrics`** - Export metrics in Prometheus, OpenTelemetry, or JSON formats
---
## Configuration
### Environment Variables
```bash
# Prometheus metrics server port
PROMETHEUS_PORT=12009
# Loki configuration
LOKI_URL=http://127.0.0.1:12002
LOG_FILE=/tmp/observability-mcp.log
# OpenTelemetry service name
OTEL_SERVICE_NAME=observability-mcp
# OTLP exporter endpoint (optional)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
# Metrics retention period (days)
METRICS_RETENTION_DAYS=30
```
### Alert Configuration
The server comes with pre-configured alerts for common issues:
- **CPU Usage > 90%** (Warning)
- **Memory Usage > 1GB** (Error)
- **Error Rate > 5%** (Error)
Alerts are stored persistently and can be customized through the MCP tools.
---
## Monitoring Dashboard
### Prometheus Metrics
Access metrics at: `http://127.0.0.1:12009/metrics`
Available metrics:
```
# Health checks
mcp_health_checks_total{status="healthy|degraded|unhealthy", service="..."} 1
# Performance metrics
mcp_performance_metrics_collected{service="..."} 1
# System resources
mcp_cpu_usage_percent{} 45.2
mcp_memory_usage_mb{} 1024.5
# Traces and alerts
mcp_traces_created{service="...", operation="..."} 1
mcp_alerts_triggered{type="active|anomaly"} 1
```
### Integration with Grafana & Loki
**Grafana Dashboards are State-of-the-Art for Observability**
1. **Add Data Sources in Grafana:**
- Use unified stack: Grafana http://127.0.0.1:12000, Prometheus http://127.0.0.1:12001, Loki http://127.0.0.1:12002
2. **Import Dashboards:**
- Import the provided `mcp-observability.json` dashboard
- Customize panels for your specific MCP ecosystem
3. **Log Integration:**
- Query logs with Loki: `{job="observability-mcp"} |= "ERROR"`
- Correlate metrics with logs for comprehensive troubleshooting
**Why Grafana + Loki = SOTA Observability:**
- **Unified View**: Single pane of glass for metrics, logs, and traces
- **Powerful Queries**: PromQL + LogQL for complex analysis
- **Rich Visualizations**: State-of-the-art dashboards with real-time updates
- **Alert Integration**: Native alerting with multiple notification channels
---
## Architecture
### FastMCP 3.3+ Features Leveraged
#### **OpenTelemetry Integration**
- **Distributed Tracing**: Track requests across multiple MCP servers
- **Metrics Collection**: Structured performance data collection
- **Context Propagation**: Maintain context across service boundaries
#### **Enhanced Persistent Storage**
- **Historical Data**: Store metrics and traces for trend analysis
- **Cross-Session Persistence**: Data survives server restarts
- **Efficient Storage**: Optimized for time-series data
#### **Production Architecture**
```
MCP Servers Observability Prometheus
(Monitored) MCP Server Metrics
Persistent Grafana
Storage Dashboards
(State-of-Art)
Application Loki
Logs Log Aggregation
```
---
## Usage Examples
### Health Monitoring
```python
# Check MCP server health
result = await monitor_server_health(
service_url="http://localhost:8000/health",
timeout_seconds=5.0
)
print(f"Status: {result['health_check']['status']}")
```
### Performance Analysis
```python
# Collect system metrics
metrics = await collect_performance_metrics(service_name="my-mcp-server")
print(f"CPU: {metrics['metrics']['cpu_percent']}%")
print(f"Memory: {metrics['metrics']['memory_mb']} MB")
```
### Distributed Tracing
```python
# Record a trace
trace = await trace_mcp_calls(
operation_name="process_document",
service_name="ocr-mcp",
duration_ms=150.5,
attributes={"file_size": "2.3MB", "format": "PDF"}
)
```
### Generate Reports
```python
# Create performance report
report = await generate_performance_reports(
service_name="web-mcp",
days=7
)
print("Performance Summary:", report['summary'])
print("Recommendations:", report['recommendations'])
```
### Loki Log Management
```python
# Send custom logs to Loki
result = await send_logs_to_loki(
log_message="User authentication failed",
level="warning",
labels={"service": "auth-service", "user_id": "12345"}
)
# Query logs from Loki
logs = await query_loki_logs(
query='{job="observability-mcp"} |= "ERROR"',
start_time="1h",
limit=100
)
# Analyze log patterns
patterns = await analyze_log_patterns(
query='{service="web-mcp"}',
time_window="24h",
min_occurrences=10
)
# Correlate logs with metrics
correlation = await correlate_logs_and_metrics(
log_query='{service="api"} |= "timeout"',
metric_query="rate(http_requests_total{status='500'}[5m])",
time_window="1h"
)
```
---
## Development
### Running Tests
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run with coverage
pytest --cov=observability_mcp --cov-report=html
```
### Code Quality
```bash
# Format code
black src/
# Lint code
ruff check src/
# Type checking
mypy src/
```
### Docker Development
```bash
# Build development image
docker build -t observability-mcp:dev -f Dockerfile.dev .
# Run with hot reload
docker run -p 12009:12009 -e PROMETHEUS_PORT=12009 -v $(pwd):/app observability-mcp:dev
```
---
## Performance Benchmarks
### FastMCP 3.3+ Benefits
- **OpenTelemetry Overhead**: <1ms per trace
- **Storage Performance**: 1000+ metrics/second
- **Memory Usage**: 50MB baseline + 10MB per monitored service
- **Concurrent Monitoring**: 100+ services simultaneously
### Recommended Hardware
- **CPU**: 2+ cores for metrics processing
- **RAM**: 2GB minimum, 4GB recommended
- **Storage**: 10GB for metrics history (30 days retention)
---
## Troubleshooting
### Common Issues
#### Server Won't Start
```bash
# Check Python version
python --version # Should be 3.11+
# Check FastMCP installation
pip show fastmcp # Should be 2.14.1+
# Check dependencies
pip check
```
#### Metrics Not Appearing
```bash
# Check Prometheus endpoint
curl http://127.0.0.1:12009/metrics
# Verify OpenTelemetry configuration
observability-mcp metrics
```
#### High Memory Usage
- Reduce `METRICS_RETENTION_DAYS`
- Implement metric aggregation
- Monitor with `monitor_system_resources`
#### Storage Issues
- Check available disk space
- Clean old metrics: `rm -rf ~/.observability-mcp/metrics/*`
- Restart server to recreate storage
---
## Contributing
### Development Setup
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request
### Code Standards
- **FastMCP 3.3++**: Use latest features and patterns
- **OpenTelemetry**: Follow OTEL practices
- **Async First**: All operations should be async
- **Type Hints**: Full type coverage required
- **Documentation**: Comprehensive docstrings
### Testing Strategy
- **Unit Tests**: Core functionality
- **Integration Tests**: MCP server interactions
- **Performance Tests**: Benchmarking and load testing
- **Chaos Tests**: Failure scenario testing
---
## 🛡️ Industrial Quality Stack
This project adheres to **SOTA 14.1** industrial standards for high-fidelity agentic orchestration:
- **Python (Core)**: [Ruff](https://astral.sh/ruff) for linting and formatting. Zero-tolerance for `print` statements in core handlers (`T201`).
- **Webapp (UI)**: [Biome](https://biomejs.dev/) for sub-millisecond linting. Strict `noConsoleLog` enforcement.
- **Protocol Compliance**: Hardened `stdout/stderr` isolation to ensure crash-resistant JSON-RPC communication.
- **Automation**: [Justfile](./justfile) recipes for all fleet operations (`just lint`, `just fix`, `just dev`).
- **Security**: Automated audits via `bandit` and `safety`.
## License
MIT License - see [LICENSE](LICENSE) file for details.
---
## Acknowledgments
- **FastMCP Team** - For the 2.14.1 framework with OpenTelemetry integration
- **OpenTelemetry Community** - For the observability standards and tools
- **Prometheus Team** - For the metrics collection and alerting system
- **Grafana Labs** - For Loki log aggregation and Grafana's state-of-the-art dashboarding
- **Grafana Community** - For the visualization platform that powers modern observability
---
## Related Projects
- [**FastMCP**](https://github.com/jlowin/fastmcp) - The framework this server is built on
- [**OpenTelemetry Python**](https://opentelemetry.io/docs/python/) - Observability instrumentation
- [**Prometheus**](https://prometheus.io) - Metrics collection and alerting
- [**Grafana**](https://grafana.com) - State-of-the-art dashboards and visualization
- [**Loki**](https://grafana.com/oss/loki/) - Log aggregation and querying
- [**Promtail**](https://grafana.com/docs/loki/latest/clients/promtail/) - Log shipping agent
---
**Built with using FastMCP 3.3+, OpenTelemetry, Prometheus, Grafana & Loki - State-of-the-Art Observability**
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available