linux-profiler
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@linux-profiler profile process nginx and generate flame graph"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Linux Performance Profiler
A comprehensive Linux system performance profiler with MCP (Model Context Protocol) remote invocation support, featuring advanced process profiling and flame graph generation.
δΈζζζ‘£ | English
License
This project is licensed under the Apache License 2.0.
Related MCP server: Linux MCP Server
Features
CPU Analysis: Usage rate, frequency, load average, per-core status
Memory Analysis: Virtual memory, swap space, cache usage
Disk Analysis: Partition usage, I/O read/write statistics
Network Analysis: Interface traffic, connection status, error statistics
Process Analysis: Top N CPU/memory consumers, process status statistics
π₯ Process Search: π Search processes by name or command line keywords
π₯ Performance Profiling: π Profile processes with perf and generate CPU flame graphs
Health Check: Automatic identification of performance issues and alerts
Project Structure
linux-profiler-tool/
βββ src/linux_profiler/
β βββ __init__.py
β βββ server.py # MCP server main entry
β βββ collectors/
β βββ __init__.py
β βββ base.py # Collector base class
β βββ cpu.py # CPU metrics collector
β βββ memory.py # Memory metrics collector
β βββ disk.py # Disk I/O collector
β βββ network.py # Network metrics collector
β βββ process.py # Process metrics & search collector
β βββ perf.py # π Perf profiling & flame graph collector
βββ examples/
β βββ profile_workflow.py # π Interactive profiling demo
βββ pyproject.toml
βββ mcp_config.json # MCP configuration example
βββ FEATURES.md # π Detailed feature documentation
βββ CHANGELOG.md # π Version changelog
βββ LICENSE # Apache 2.0 License
βββ README.mdInstallation
# Clone the project
cd linux-profiler-tool
# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate # Linux/macOS
# or .venv\Scripts\activate # Windows
# Install dependencies (development mode)
pip install -e .
# Or use uv (faster)
uv pip install -e .
# Verify installation
linux-profiler --helpNote: If you encounter
ModuleNotFoundError, ensure you're in the project directory and have activated the virtual environment. Runpip install -e .to install in development mode.
Usage
1. STDIO Mode (Local Invocation)
# Run directly (default STDIO mode)
python -m linux_profiler.server
# Or use the installed command
linux-profiler2. HTTP Mode (Remote Invocation)
Two HTTP transport protocols are supported:
Streamable HTTP (Recommended, MCP new standard):
# Start Streamable HTTP service (default)
linux-profiler --http
# Stateless mode
linux-profiler --http --stateless
# Custom port
linux-profiler --http --port 22222SSE Transport (Legacy mode):
# Use SSE transport
linux-profiler --http --transport sseSupport both transports simultaneously:
# Enable both SSE and Streamable HTTP
linux-profiler --http --transport bothAvailable endpoints after startup:
Transport Type | Endpoint | Description |
Streamable HTTP |
| MCP main endpoint (GET/POST/DELETE) |
SSE |
| SSE connection endpoint |
SSE |
| SSE message endpoint (both mode only) |
Common |
| Health check |
Common |
| Service information |
3. Configure MCP Client
STDIO Mode Configuration:
{
"mcpServers": {
"linux-profiler": {
"command": "python",
"args": ["-m", "linux_profiler.server"],
"cwd": "/path/to/linux-profiler-tool",
"env": {
"PYTHONPATH": "/path/to/linux-profiler-tool/src"
}
}
}
}Streamable HTTP Mode Configuration (Recommended):
{
"mcpServers": {
"linux-profiler": {
"url": "http://your-server:22222/mcp",
"transportType": "streamable-http"
}
}
}SSE Mode Configuration (Legacy):
{
"mcpServers": {
"linux-profiler": {
"url": "http://your-server:22222/sse"
}
}
}Available MCP Tools
Core Monitoring Tools
Tool Name | Description |
| Get basic system information (hostname, OS, kernel version, etc.) |
| Get CPU usage, frequency, and load average |
| Get memory and swap space usage |
| Get disk partition and I/O statistics |
| Get network interface traffic and connection status |
| Get process statistics and top N resource consumers |
| Get comprehensive report of all performance metrics |
| Get performance summary and issue alerts |
π Advanced Profiling Tools (v1.1.0)
Tool Name | Description | Parameters |
| Search processes by keyword (name or command line) |
|
| Profile process using Linux perf, generate flame graph data |
|
π₯ New Features:
Process Search: Quickly find processes by name or command patterns
CPU Profiling: Deep performance analysis with perf tool integration
Flame Graph Generation: Interactive HTML flame graphs for performance visualization
See FEATURES.md for detailed documentation and examples.
Example Output
get_performance_summary
{
"status": "warning",
"timestamp": "2026-01-14T10:30:00",
"summary": {
"cpu_percent": 45.2,
"load_average_1min": 2.5,
"memory_percent": 72.3,
"swap_percent": 15.0
},
"issues": [],
"warnings": [
"Warning: Memory usage is high (72.3%)"
]
}search_processes
{
"success": true,
"keyword": "nginx",
"case_sensitive": false,
"matched_count": 3,
"processes": [
{
"pid": 1234,
"name": "nginx",
"username": "www-data",
"cmdline": "nginx: master process /usr/sbin/nginx",
"cpu_percent": 0.5,
"memory_percent": 0.3,
"status": "sleeping"
},
{
"pid": 1235,
"name": "nginx",
"username": "www-data",
"cmdline": "nginx: worker process",
"cpu_percent": 2.1,
"memory_percent": 0.4,
"status": "running"
}
],
"tip": "Use the PID from this list to profile a specific process with profile_process tool"
}profile_process
{
"success": true,
"pid": 1234,
"duration": 30,
"frequency": 99,
"event": "cpu-clock",
"timestamp": "2026-01-18 07:42:12",
"statistics": {
"total_samples": 287,
"top_functions": [
{
"overhead_percent": 15.2,
"command": "nginx",
"function": "ngx_http_process_request"
},
{
"overhead_percent": 8.7,
"command": "nginx",
"function": "ngx_event_process_posted"
}
]
},
"flame_graph_data": [
"nginx;[libc] __GI___libc_write;ngx_write_channel 12",
"nginx;ngx_event_process_posted;ngx_http_request_handler 45"
],
"help": "Use flame_graph_data to generate flame graph visualization"
}get_system_info
{
"hostname": "web-server-01",
"system": "Linux",
"kernel_version": "5.15.0-91-generic",
"architecture": "x86_64",
"python_version": "3.10.12",
"boot_time": "2026-01-10T08:30:00"
}get_cpu_metrics
{
"cpu_percent": 35.5,
"cpu_count": {
"physical": 8,
"logical": 16
},
"cpu_freq": {
"current": 2400.0,
"min": 800.0,
"max": 3800.0
},
"load_average": {
"1min": 2.15,
"5min": 1.89,
"15min": 1.76
},
"per_cpu_percent": [25.0, 38.5, 42.1, 30.0, ...],
"cpu_times_percent": {
"user": 25.5,
"system": 8.0,
"idle": 66.5,
"iowait": 0.0
}
}Command Line Arguments
Argument | Description |
| Enable HTTP mode (default is STDIO mode) |
| HTTP listening port (default: 22222) |
| HTTP listening address (default: 0.0.0.0) |
| Transport type: |
| Streamable HTTP stateless mode |
Environment Variables
Variable | Description | Default |
| HTTP default port | 22222 |
| HTTP default address | 0.0.0.0 |
| Default transport type | streamable |
Dependencies
Core Dependencies
Python >= 3.10
mcp >= 1.0.0
psutil >= 5.9.0
starlette >= 0.27.0
uvicorn >= 0.24.0
pydantic >= 2.0.0
Additional Requirements for Profiling (profile_process)
Linux system (perf is Linux-specific)
perf tool installed:
# Ubuntu/Debian sudo apt-get install linux-tools-generic linux-tools-$(uname -r) # RHEL/CentOS sudo yum install perf # Arch Linux sudo pacman -S perf
Optional: Enable perf for non-root users
# Temporarily (until reboot)
sudo sysctl -w kernel.perf_event_paranoid=-1
# Permanently
echo "kernel.perf_event_paranoid = -1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -pUse Cases
1. Local Performance Monitoring
Monitor your local machine's performance metrics in real-time through MCP-compatible AI assistants.
2. Remote Server Monitoring
Deploy the profiler on remote servers and monitor multiple servers centrally through HTTP endpoints.
3. AI-Powered DevOps
Integrate with AI assistants to automate performance analysis, anomaly detection, and troubleshooting recommendations.
4. System Health Checks
Set up automated health checks and receive alerts when system resources exceed thresholds.
5. π Process Performance Analysis
Search for resource-intensive processes and generate detailed CPU flame graphs to identify bottlenecks.
Example Workflow:
# 1. Search for processes
search_processes --keyword "python"
# 2. Profile the target process
profile_process --pid 12345 --duration 30
# 3. Generate interactive flame graph
# The tool outputs flame_graph_data that can be visualized with:
# - FlameGraph tools (https://github.com/brendangregg/FlameGraph)
# - speedscope (https://www.speedscope.app/)
# - Or the built-in HTML generator6. π Performance Bottleneck Identification
Quickly identify CPU-intensive functions and optimize hot code paths using flame graph visualization.
Try the Interactive Demo:
python examples/profile_workflow.pyDevelopment
Running Tests
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run with coverage
pytest --cov=linux_profilerCode Quality
# Format code
black src/
# Type checking
mypy src/
# Linting
ruff check src/Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (
git checkout -b feature/AmazingFeature)Commit your changes (
git commit -m 'Add some AmazingFeature')Push to the branch (
git push origin feature/AmazingFeature)Open a Pull Request
Troubleshooting
For common issues and solutions, please refer to:
INSTALL.md - Detailed installation guide
FIX_GUIDE.md - Troubleshooting guide
Acknowledgments
Built with MCP (Model Context Protocol)
Performance metrics powered by psutil
HTTP server built with Starlette
License
Copyright 2026 Linux Profiler MCP Contributors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.See LICENSE for the full license text.
Made with β€οΈ for the DevOps and AI community
Available Tools
10 toolsget_all_metricsB
Get a comprehensive performance report including CPU, memory, disk, network, and process metrics.
Inputs: include_processes.
get_cpu_metricsB
Collects CPU usage, frequency, load average, and time distribution metrics.
Inputs: no named parameters.
get_disk_metricsA
Collects disk partition usage and I/O statistics including read/write counts and times.
Inputs: no named parameters.
get_memory_metricsA
Collects virtual memory and swap usage metrics including buffers and cache.
Inputs: no named parameters.
get_network_metricsA
Collects network I/O statistics, interface addresses, and connection states.
Inputs: no named parameters.
get_performance_summaryB
Get a brief performance summary with key metrics and potential issues.
Inputs: no named parameters.
get_process_metricsA
Collects process statistics including top 10 CPU and memory consumers.
Inputs: top_n.
get_system_infoA
Get basic system information including hostname, OS, kernel version, and architecture.
Inputs: no named parameters.
profile_processA
Profile a specific process using perf to collect performance data for flame graph generation. Requires perf tool to be installed on the system.
Inputs: pid (required), duration, frequency, event.
search_processesA
Search for processes by keyword (name or command line). Returns matching process IDs and details.
Inputs: keyword (required), case_sensitive.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 10 tools
Each tool targets a distinct aspect of system performance: specific subsystems (CPU, memory, disk, network, processes), a comprehensive overview, a brief summary, system info, process profiling, and process search. There is no overlap that would confuse an agent.
The majority of tools follow a consistent 'get_<subsystem>_metrics' pattern. Two tools use 'get_' with different objects (summary, info), and two use different verbs (profile, search). This is mostly consistent with minor deviations.
10 tools is well-suited for a Linux profiler server. Each tool serves a clear purpose without being redundant or excessive, covering the necessary scope for performance monitoring and profiling.
The tool set covers all major performance domains (CPU, memory, disk, network, processes) and includes a comprehensive report, a summary, system info, and advanced per-process profiling. This provides a complete surface for typical Linux performance analysis.
Maintenance
Related MCP Connectors
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Secure Linux sandboxes for AI agents, as MCP tools.
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThis is a Model Context Protocol (MCP) server implemented in Go, providing a tool to analyze Go pprof performance profiles.50MIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server for Linux and macOS system administration, diagnostics, and troubleshooting, supporting remote SSH execution and multi-host management.Apache 2.0
- AlicenseAqualityCmaintenanceMCP server for profiling Python processes using py-spy, supporting flamegraphs, stack dumps, and performance comparisons.614 PyPI3MIT
- AlicenseBqualityDmaintenanceA powerful MCP server for reading and modifying Linux /proc filesystem values, providing system monitoring, process management, and sysctl operations via JSON-RPC and SSE.14MIT