MCP System Monitor Server

Um servidor multiplataforma para monitoramento em tempo real de informações de CPU, GPU, memória, disco, rede e processos.

GitHub

Experimente este MCPPatrocinado

Documentação

MCP System Monitor Server

Um servidor MCP (Model Context Protocol) multiplataforma que fornece recursos abrangentes de monitoramento de sistema em tempo real para LLMs. Construído com FastMCP para fácil integração com o Claude Desktop e outros clientes compatíveis com MCP.

Recursos

Monitoramento do Sistema

Monitoramento Básico do Sistema:

Monitoramento de CPU: Uso em tempo real, estatísticas por núcleo, frequência, temperatura, informações detalhadas do processador (modelo, fabricante, arquitetura, tamanhos de cache)
Monitoramento de GPU: Suporte a GPUs de múltiplos fabricantes (NVIDIA com métricas completas, Apple Silicon com suporte abrangente incluindo memória unificada e contagem de núcleos, AMD/Intel com informações básicas)
Monitoramento de Memória: Uso de RAM e swap, estatísticas de disponibilidade
Monitoramento de Disco: Uso de espaço, informações do sistema de arquivos para todas as unidades montadas
Estatísticas de Rede: Tráfego em nível de interface e contadores de erros
Monitoramento de Processos: Principais processos por uso de CPU/memória
Informações do Sistema: Detalhes do SO, nome do host, tempo de atividade, arquitetura

Monitoramento de Desempenho da Fase 1:

Desempenho de I/O: Métricas detalhadas de I/O de disco, taxas de leitura/escrita, estatísticas por disco, análise de tempo ocupado
Carga do Sistema: Médias de carga (1m, 5m, 15m), trocas de contexto, interrupções, processos em execução/bloqueados
Memória Aprimorada: Estatísticas detalhadas de memória incluindo buffers, cache, memória ativa/inativa, falhas de página, atividade de swap
Rede Aprimorada: Métricas de desempenho de rede com taxas de transferência, erros, descartes, velocidade da interface e MTU

Ferramentas MCP Disponíveis

Monitoramento Básico do Sistema (9 ferramentas):

get_current_datetime: Obter a data/hora local atual no formato ISO
get_cpu_info: Obter uso e estatísticas atuais da CPU
get_gpu_info: Obter informações de GPU para todas as GPUs detectadas
get_memory_info: Obter uso de RAM e swap
get_disk_info: Obter uso de disco para todas as unidades montadas
get_system_snapshot: Obter o estado completo do sistema em uma única chamada
monitor_cpu_usage: Monitorar o uso da CPU por uma duração especificada
get_top_processes: Obter os principais processos por uso de CPU ou memória
get_network_stats: Obter estatísticas de interface de rede

Monitoramento de Desempenho da Fase 1 (6 ferramentas):

get_io_performance: Obter métricas e taxas detalhadas de desempenho de I/O
get_system_load: Obter médias de carga do sistema e estatísticas de processos
get_enhanced_memory_info: Obter estatísticas detalhadas de memória com caches/buffers
get_enhanced_network_stats: Obter métricas aprimoradas de desempenho de rede
get_performance_snapshot: Obter um instantâneo completo do monitoramento de desempenho
monitor_io_performance: Monitorar o desempenho de I/O por duração especificada com análise de tendências

Recursos MCP

Recursos Básicos do Sistema (3 recursos):

system://live/cpu: Dados de uso da CPU em tempo real
system://live/memory: Dados de uso de memória em tempo real
system://config: Configuração do sistema e informações de hardware

Recursos de Desempenho da Fase 1 (3 recursos):

system://performance/io: Dados de desempenho de I/O em tempo real
system://performance/load: Dados de carga do sistema em tempo real
system://performance/network: Dados de desempenho de rede em tempo real

Detalhes de Suporte a GPU

GPUs NVIDIA:

Métricas completas: porcentagem de uso, memória (usada/total), temperatura, consumo de energia
Suporta múltiplas GPUs NVIDIA
Requer drivers NVIDIA e bibliotecas NVML

GPUs Apple Silicon:

Suporte abrangente para chips M1, M2 e M3
Detecção da contagem de núcleos da GPU
Relatório de memória unificada (compartilha a RAM do sistema)
Detecção de suporte à API Metal
Monitoramento de temperatura (quando disponível)

GPUs AMD/Intel:

Detecção e identificação básicas
Métricas limitadas dependendo da plataforma e dos drivers

Requisitos

Python 3.10+
Windows, macOS ou Linux
GPU (opcional): GPUs NVIDIA para métricas completas, GPUs Apple Silicon totalmente suportadas no macOS

Instalação

A partir do GitHub

Clone o repositório:

git clone https://github.com/huhabla/mcp-system-monitor.git
cd mcp-system-monitor

Instale as dependências usando uv (recomendado):
```
uv pip install -e .
```
Ou usando pip:
```
pip install -e .
```

Dependências Opcionais

Para recursos específicos do Windows:

pip install mcp-system-monitor[win32]

Uso

Modo de Desenvolvimento

Teste o servidor com o MCP Inspector:

uv run mcp dev mcp_system_monitor_server.py

Integração com o Claude Desktop

Instale o servidor no Claude Desktop:

uv run mcp install mcp_system_monitor_server.py --name "System Monitor"

Execução Direta

Execute o servidor diretamente:

python mcp_system_monitor_server.py

Configuração JSON dos Servidores MCP

Modifique o seguinte modelo JSON para definir o caminho para o servidor MCP no seu cliente MCP para Windows:

{
  "mcpServers": {
    "mpc-system-monitor": {
      "command": "cmd",
      "args": [
        "/c",
        "C:/Users/Sören Gebbert/Documents/GitHub/mcp-system-monitor/start_mpc_system_monitor.bat"
      ]
    }
  }
}

Modifique o seguinte modelo JSON para definir o caminho para o servidor MCP no seu cliente MCP para MacOS:

{
  "mcpServers": {
    "mpc-system-monitor": {
      "command": "/bin/zsh",
      "args": [
        "/Users/holistech/Documents/GitHub/mcp-system-monitor/start_mcp_system_monitor.sh"
      ]
    }
  }
}

Exemplo de Uso das Ferramentas

Depois de conectado ao Claude Desktop ou a outro cliente MCP, você pode usar linguagem natural para interagir com o monitor de sistema:

Monitoramento Básico do Sistema:

"Mostre-me o uso atual da CPU"
"Qual é a temperatura da minha GPU?"
"Quantos núcleos de GPU tem o meu Apple M1 Max?"
"Mostre-me o uso de memória da GPU e se é memória unificada"
"Quanto espaço em disco está disponível?"
"Monitore o uso da CPU pelos próximos 10 segundos"
"Mostre-me os 5 principais processos por uso de memória"
"Obtenha um instantâneo completo do sistema"

Monitoramento de Desempenho da Fase 1:

"Mostre-me métricas detalhadas de desempenho de I/O"
"Qual é a média de carga atual do sistema?"
"Monitore o desempenho de I/O pelos próximos 30 segundos"
"Mostre-me estatísticas aprimoradas de memória com informações de cache"
"Obtenha métricas detalhadas de desempenho de rede"
"Forneça um instantâneo completo de desempenho"

Arquitetura

O servidor usa uma arquitetura modular baseada em coletores:

BaseCollector: Classe base abstrata que fornece cache e coleta de dados assíncrona
Coletores Especializados: Coletores de CPU, GPU, Memória, Disco, Rede, Processos e Sistema
Coletores de Desempenho da Fase 1: Coletores IOPerformance, SystemLoad, EnhancedMemory e EnhancedNetwork
Modelos Pydantic: Modelos de dados type-safe para todas as informações do sistema
Integração FastMCP: Decoradores simples para expor ferramentas e recursos

Estratégia de Cache

Todos os coletores implementam cache inteligente para:

Reduzir a sobrecarga do sistema com polling frequente
Fornecer dados consistentes dentro de janelas de tempo
Permitir expiração de cache configurável

Testes

Suíte de Testes Abrangente

O projeto inclui uma suíte de testes abrangente com 100% de cobertura de todas as ferramentas, recursos e coletores MCP:

Organização dos Testes:

test_mcp_system_monitor_server.py - Testes originais dos coletores básicos
test_mcp_system_monitor_server_comprehensive.py - Testes abrangentes de ferramentas/recursos MCP
test_mcp_server_integration.py - Testes de integração para conformidade com o protocolo do servidor MCP
test_architecture_agnostic.py - Testes multiplataforma com foco em contratos de dados
conftest.py - Configuração de testes, fixtures e utilitários de mocking

Executando Testes

Execute todos os testes:

pytest

Execute testes por categoria:

pytest -m unit              # Fast unit tests only
pytest -m integration       # Integration tests only
pytest -m agnostic          # Architecture/OS agnostic tests
pytest -m "not slow"        # Exclude slow tests
pytest -m "unit and not slow"  # Fast unit tests for CI

Execute suítes de testes específicas:

pytest tests/test_mcp_system_monitor_server_comprehensive.py  # All MCP endpoints
pytest tests/test_mcp_server_integration.py                  # Integration tests
pytest tests/test_architecture_agnostic.py                   # Cross-platform tests

Execute com cobertura:

pytest --cov=mcp_system_monitor_server --cov-report=html

Cobertura de Testes

Cobertura Completa:

15 Ferramentas MCP (9 básicas + 6 de desempenho da Fase 1)
6 Recursos MCP (3 básicos + 3 de desempenho da Fase 1)
11 Coletores (7 básicos + 4 de desempenho da Fase 1)
Testes de compatibilidade multiplataforma
Benchmarking de desempenho e testes de estresse
Tratamento de erros e validação de casos extremos

Benchmarks de Desempenho:

Coleta de instantâneo do sistema: < 5 segundos
Chamadas individuais de ferramentas: < 1 segundo cada
Operações concorrentes: 20 chamadas paralelas < 10 segundos

Suporte a Plataformas

Recurso	Windows	macOS	Linux
Monitoramento de CPU	✅	✅	✅
Monitoramento de GPU (NVIDIA)	✅	✅	✅
Monitoramento de GPU (AMD)	⚠️	❌	⚠️
Monitoramento de GPU (Intel)	⚠️	❌	⚠️
Monitoramento de GPU (Apple)	❌	✅	❌
Monitoramento de Memória	✅	✅	✅
Monitoramento de Disco	✅	✅	✅
Estatísticas de Rede	✅	✅	✅
Monitoramento de Processos	✅	✅	✅
Temperatura da CPU	⚠️	⚠️	✅

⚠️ = Suporte limitado, depende de hardware/drivers

Solução de Problemas

Monitoramento de GPU Não Funciona

GPUs NVIDIA:

Certifique-se de que os drivers NVIDIA estejam instalados
Verifique se o comando nvidia-smi funciona
O servidor lidará graciosamente com bibliotecas de GPU ausentes

GPUs Apple Silicon:

Suportadas no macOS com chips M1, M2 e M3
Fornece informações abrangentes incluindo memória unificada e contagem de núcleos da GPU
Usa o comando system_profiler (disponível por padrão no macOS)

Erros de Permissão

Algumas informações do sistema podem exigir privilégios elevados
O servidor lida com erros de permissão graciosamente e ignora recursos inacessíveis

Alto Uso de CPU

Ajuste a frequência de monitoramento modificando os intervalos de atualização dos coletores
Use métodos de dados em cache para reduzir chamadas de sistema
A expiração padrão do cache é de 2 segundos para a maioria dos coletores
Considere aumentar o parâmetro max_age nas chamadas get_cached_data() para atualizações menos frequentes

Considerações de Desempenho

O servidor usa cache inteligente para minimizar chamadas de sistema
Cada coletor mantém seu próprio cache com expiração configurável
Ferramentas de monitoramento contínuo (como monitor_cpu_usage) ignoram o cache para dados em tempo real
Para polling de alta frequência, considere usar os endpoints de recursos que aproveitam o cache

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

Construído com FastMCP
Monitoramento de sistema via psutil
Suporte a GPU NVIDIA via nvidia-ml-py