System Information MCP Server

Fornece informações e métricas do sistema em tempo real, incluindo status de CPU, memória, disco, rede e processos.

Documentação

Servidor MCP de Informações do Sistema

Um servidor Model Context Protocol (MCP) que fornece informações e métricas do sistema em tempo real. Este servidor expõe uso de CPU, estatísticas de memória, informações de disco, status de rede e processos em execução por meio de uma interface MCP padronizada.

Recursos

🛠️ Ferramentas Disponíveis

get_cpu_info - Recupera uso de CPU, contagem de núcleos, frequência e média de carga
get_memory_info - Obtém estatísticas de memória virtual e swap
get_disk_info - Informações de uso de disco para todos os pontos de montagem ou caminhos específicos
get_network_info - Informações de interface de rede e estatísticas de I/O
get_process_list - Processos em execução com opções de ordenação e filtragem
get_system_uptime - Informações de tempo de inicialização e uptime do sistema
get_temperature_info - Sensores de temperatura e velocidades de ventoinha (quando disponíveis)

📚 Recursos Disponíveis

system://overview - Visão geral abrangente do sistema com todas as métricas
system://processes - Recurso de lista de processos atual

⭐ Principais Recursos

Métricas em tempo real com cache configurável
Suporte multiplataforma (Windows, macOS, Linux)
Foco em segurança com filtragem de dados sensíveis
Desempenho otimizado com cache inteligente
Tratamento abrangente de erros
Configuração por variáveis de ambiente

Instalação

Usando uvx (Recomendado)

A maneira mais fácil de instalar e usar este servidor MCP é com uvx:

uvx install mcp-system-info

Em seguida, configure-o no seu cliente MCP (como o Claude Desktop):

{
  "mcpServers": {
    "system-info": {
      "command": "uvx",
      "args": ["mcp-system-info"]
    }
  }
}

Instalação para Desenvolvimento

Para desenvolvimento local:

Clone o repositório:

git clone <repository-url>
cd mcp-system-info

Instale as dependências:
```
uv sync
```
Execute o servidor:
```
uv run mcp-system-info
```

Desenvolvimento

Estrutura do Projeto

mcp-system-info/
├── src/
│   └── system_info_mcp/
│       ├── __init__.py
│       ├── server.py          # Main FastMCP server
│       ├── tools.py           # Tool implementations
│       ├── resources.py       # Resource handlers
│       ├── config.py          # Configuration management
│       └── utils.py           # Utility functions
├── tests/                     # Comprehensive test suite
├── pyproject.toml            # Project configuration
└── README.md

Configuração de Desenvolvimento

Instale as dependências de desenvolvimento:
```
uv sync --dev
```
Execute os testes:
```
uv run pytest
```

Execute os testes com cobertura:

uv run pytest --cov=system_info_mcp --cov-report=term-missing

Formate o código:
```
uv run black src/ tests/
```
Verifique o código (lint):
```
uv run ruff check src/ tests/
```
Verificação de tipos:
```
uv run mypy src/
```

Compilação e Publicação

Compilar o Pacote

# Build distribution files
uv build

Isso cria arquivos de distribuição no diretório dist/:

mcp_system_info-*.whl (arquivo wheel)
mcp_system_info-*.tar.gz (distribuição de código-fonte)

Teste Local com uvx

Teste o pacote localmente antes de publicar:

# Test running the command directly from wheel file
uvx --from ./dist/mcp_system_info-*.whl mcp-system-info

# Test with environment variables
SYSINFO_LOG_LEVEL=DEBUG uvx --from ./dist/mcp_system_info-*.whl mcp-system-info

Publicação no PyPI

# Publish to PyPI (requires PyPI account and token)
uv publish

# Or publish to TestPyPI first
uv publish --repository testpypi

Observação: Você precisará:

Criar uma conta no PyPI em https://pypi.org
Gerar um token de API nas configurações da sua conta
Configurar o uv com suas credenciais ou usar variáveis de ambiente

Configuração de Ambiente

O servidor suporta configuração por meio de variáveis de ambiente:

Configurações Principais

SYSINFO_CACHE_TTL - Tempo de vida do cache em segundos (padrão: 5)
SYSINFO_MAX_PROCESSES - Número máximo de processos a retornar (padrão: 100)
SYSINFO_ENABLE_TEMP - Ativar sensores de temperatura (padrão: true)
SYSINFO_LOG_LEVEL - Nível de registro (log) (padrão: INFO)

Configuração de Transporte

SYSINFO_TRANSPORT - Protocolo de transporte: stdio, sse ou streamable-http (padrão: stdio)
SYSINFO_HOST - Host para vincular em transportes HTTP (padrão: localhost)
SYSINFO_PORT - Porta para vincular em transportes HTTP (padrão: 8001)
SYSINFO_MOUNT_PATH - Caminho de montagem para transporte SSE (padrão: /mcp)

Modos de Transporte

1. STDIO (Padrão)

# Uses standard input/output - no network port
uv run mcp-system-info

2. SSE (Server-Sent Events)

# HTTP server with real-time streaming
SYSINFO_TRANSPORT=sse SYSINFO_PORT=8001 uv run mcp-system-info
# Server will be available at http://localhost:8001/mcp

3. HTTP Transmissível (Streamable)

# HTTP server with request/response
SYSINFO_TRANSPORT=streamable-http SYSINFO_PORT=9000 uv run mcp-system-info

Exemplo Completo:

SYSINFO_TRANSPORT=sse \
SYSINFO_HOST=0.0.0.0 \
SYSINFO_PORT=8001 \
SYSINFO_CACHE_TTL=10 \
SYSINFO_LOG_LEVEL=DEBUG \
uv run mcp-system-info

Exemplos de Uso

Uso de Ferramentas

Obter Informações de CPU

# Basic CPU info
{
  "name": "get_cpu_info_tool",
  "arguments": {
    "interval": 1.0,
    "per_cpu": false
  }
}

Obter Lista de Processos

# Top 10 processes by memory usage
{
  "name": "get_process_list_tool", 
  "arguments": {
    "limit": 10,
    "sort_by": "memory",
    "filter_name": "python"
  }
}

Obter Informações de Disco

# All disk usage
{
  "name": "get_disk_info_tool",
  "arguments": {}
}

# Specific path
{
  "name": "get_disk_info_tool",
  "arguments": {
    "path": "/home"
  }
}

Uso de Recursos

Visão Geral do Sistema

# Request comprehensive system overview
{
  "uri": "system://overview"
}

Recurso de Lista de Processos

# Get top processes resource
{
  "uri": "system://processes" 
}

Integração com o Claude Desktop

Adicionando ao Claude Desktop

Localize o arquivo de configuração do Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Adicione a configuração do servidor MCP:

Usando uvx (Recomendado)

{
  "mcpServers": {
    "system-info": {
      "command": "uvx",
      "args": ["mcp-system-info"],
      "env": {
        "SYSINFO_CACHE_TTL": "10",
        "SYSINFO_LOG_LEVEL": "INFO"
      }
    }
  }
}

Para Desenvolvimento Local

{
  "mcpServers": {
    "system-info": {
      "command": "uv",
      "args": [
        "--directory", 
        "/path/to/mcp-system-info", 
        "run", 
        "mcp-system-info"
      ],
      "env": {
        "SYSINFO_TRANSPORT": "stdio",
        "SYSINFO_CACHE_TTL": "10",
        "SYSINFO_LOG_LEVEL": "INFO"
      }
    }
  }
}

Para Transporte HTTP (SSE)

{
  "mcpServers": {
    "system-info-http": {
      "command": "uvx",
      "args": ["mcp-system-info"],
      "env": {
        "SYSINFO_TRANSPORT": "sse",
        "SYSINFO_HOST": "localhost",
        "SYSINFO_PORT": "8001",
        "SYSINFO_MOUNT_PATH": "/mcp"
      }
    }
  }
}

Reinicie o Claude Desktop para carregar o novo servidor.

Usando com o Claude

Uma vez configurado, você pode pedir ao Claude para:

"Qual é o meu uso atual de CPU?"
"Mostre-me os 10 processos que mais usam memória"
"Quanto espaço em disco está disponível?"
"Qual é o uptime do meu sistema?"
"Dê-me uma visão geral completa do sistema"

Testes

Executando Testes

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_tools.py

# Run with coverage report
uv run pytest --cov=system_info_mcp --cov-report=html

Estrutura de Testes

tests/test_config.py - Testes de validação de configuração
tests/test_tools.py - Testes de implementação de ferramentas
tests/test_resources.py - Testes de manipuladores de recursos
tests/test_utils.py - Testes de funções utilitárias

Todos os testes usam dependências simuladas (mocked) para execução consistente e rápida em diferentes ambientes.

Considerações de Desempenho

Cache: O cache inteligente reduz chamadas de sistema e melhora os tempos de resposta
Intervalos configuráveis: Ajuste o TTL do cache conforme suas necessidades
Carregamento preguiçoso: Sensores de temperatura e outros recursos opcionais carregam apenas quando necessário
Suporte assíncrono: Construído sobre FastMCP para operações assíncronas eficientes

Recursos de Segurança

Operações somente leitura: Sem capacidade de modificação do sistema
Filtragem de dados sensíveis: Argumentos de linha de comando são filtrados para senhas, tokens, etc.
Validação de entrada: Todos os parâmetros são validados antes do processamento
Isolamento de erros: Falhas em uma ferramenta não afetam as outras

Suporte de Plataformas

macOS - Suporte completo, incluindo sensores de temperatura em hardware compatível
Linux - Suporte completo com disponibilidade de sensores dependente do hardware
Windows - Suporte completo com otimizações específicas da plataforma

Solução de Problemas

Problemas Comuns

Erros de permissão: Algumas informações do sistema podem exigir privilégios elevados
Sensores ausentes: A disponibilidade de dados de temperatura/ventoinha varia conforme o hardware
Impacto no desempenho: Reduza o TTL do cache ou limite as contagens de processos para melhor desempenho

Modo de Depuração

Ative o registro de depuração para solução de problemas:

SYSINFO_LOG_LEVEL=DEBUG uv run mcp-system-info

Verificando a Instalação

Teste se as ferramentas funcionam corretamente:

uv run python -c "from system_info_mcp.tools import get_cpu_info; print(get_cpu_info())"

Contribuindo

Faça um fork do repositório
Crie um branch de recurso
Faça suas alterações com testes
Execute a suíte completa de testes
Envie um pull request

Padrões de Código

Siga as diretrizes de estilo PEP 8
Adicione dicas de tipo (type hints) a todas as funções
Escreva testes para novas funcionalidades
Atualize a documentação conforme necessário

Licença

[Adicione suas informações de licença aqui]

Suporte

[Adicione informações de suporte aqui]