mcp-system-info 1.0.1
System Information MCP Server
Requires Python: >=3.10

# System Information MCP Server

A Model Context Protocol (MCP) server that provides real-time system information and metrics. This server exposes CPU usage, memory statistics, disk information, network status, and running processes through a standardized MCP interface.

## Features

### 🛠️ Tools Available

- **`get_cpu_info`** - Retrieve CPU usage, core counts, frequency, and load average
- **`get_memory_info`** - Get virtual and swap memory statistics
- **`get_disk_info`** - Disk usage information for all mounts or specific paths
- **`get_network_info`** - Network interface information and I/O statistics
- **`get_process_list`** - Running processes with sorting and filtering options
- **`get_system_uptime`** - System boot time and uptime information
- **`get_temperature_info`** - Temperature sensors and fan speeds (when available)

### 📚 Resources Available

- **`system://overview`** - Comprehensive system overview with all metrics
- **`system://processes`** - Current process list resource

### ⭐ Key Features

- **Real-time metrics** with configurable caching
- **Cross-platform support** (Windows, macOS, Linux)
- **Security-focused** with sensitive data filtering
- **Performance optimized** with intelligent caching
- **Comprehensive error handling**
- **Environment variable configuration**

## Installation

### Using uvx (Recommended)

The easiest way to install and use this MCP server is with [uvx](https://docs.astral.sh/uv/guides/tools/):

```bash
uvx install mcp-system-info
```

Then configure it in your MCP client (like Claude Desktop):

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

### Development Installation

For local development:

1. **Clone the repository:**
   ```bash
   git clone <repository-url>
   cd mcp-system-info
   ```

2. **Install dependencies:**
   ```bash
   uv sync
   ```

3. **Run the server:**
   ```bash
   uv run mcp-system-info
   ```

## Development

### Project Structure

```
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
```

### Development Setup

1. **Install development dependencies:**
   ```bash
   uv sync --dev
   ```

2. **Run tests:**
   ```bash
   uv run pytest
   ```

3. **Run tests with coverage:**
   ```bash
   uv run pytest --cov=system_info_mcp --cov-report=term-missing
   ```

4. **Format code:**
   ```bash
   uv run black src/ tests/
   ```

5. **Lint code:**
   ```bash
   uv run ruff check src/ tests/
   ```

6. **Type checking:**
   ```bash
   uv run mypy src/
   ```

### Building and Publishing

#### Build the Package

```bash
# Build distribution files
uv build
```

This creates distribution files in the `dist/` directory:
- `mcp_system_info-*.whl` (wheel file)
- `mcp_system_info-*.tar.gz` (source distribution)

#### Local Testing with uvx

Test the package locally before publishing:

```bash
# 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
```

#### Publishing to PyPI

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

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

**Note:** You'll need to:
1. Create a PyPI account at https://pypi.org
2. Generate an API token in your account settings
3. Configure uv with your credentials or use environment variables

### Environment Configuration

The server supports configuration through environment variables:

#### Core Settings
- `SYSINFO_CACHE_TTL` - Cache time-to-live in seconds (default: 5)
- `SYSINFO_MAX_PROCESSES` - Maximum processes to return (default: 100)
- `SYSINFO_ENABLE_TEMP` - Enable temperature sensors (default: true)
- `SYSINFO_LOG_LEVEL` - Logging level (default: INFO)

#### Transport Configuration
- `SYSINFO_TRANSPORT` - Transport protocol: `stdio`, `sse`, or `streamable-http` (default: stdio)
- `SYSINFO_HOST` - Host to bind to for HTTP transports (default: localhost)
- `SYSINFO_PORT` - Port to bind to for HTTP transports (default: 8001)
- `SYSINFO_MOUNT_PATH` - Mount path for SSE transport (default: /mcp)

#### Transport Modes

**1. STDIO (Default)**
```bash
# Uses standard input/output - no network port
uv run mcp-system-info
```

**2. SSE (Server-Sent Events)**
```bash
# 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. Streamable HTTP**
```bash  
# HTTP server with request/response
SYSINFO_TRANSPORT=streamable-http SYSINFO_PORT=9000 uv run mcp-system-info
```

#### Complete Example:
```bash
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
```

## Usage Examples

### Tool Usage

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

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

#### Get Disk Information
```python
# All disk usage
{
  "name": "get_disk_info_tool",
  "arguments": {}
}

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

### Resource Usage

#### System Overview
```python
# Request comprehensive system overview
{
  "uri": "system://overview"
}
```

#### Process List Resource
```python
# Get top processes resource
{
  "uri": "system://processes" 
}
```

## Integration with Claude Desktop

### Adding to Claude Desktop

1. **Locate your Claude Desktop config file:**
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

2. **Add the MCP server configuration:**

#### Using uvx (Recommended)
```json
{
  "mcpServers": {
    "system-info": {
      "command": "uvx",
      "args": ["mcp-system-info"],
      "env": {
        "SYSINFO_CACHE_TTL": "10",
        "SYSINFO_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

#### For Local Development
```json
{
  "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"
      }
    }
  }
}
```

#### For HTTP Transport (SSE)
```json
{
  "mcpServers": {
    "system-info-http": {
      "command": "uvx",
      "args": ["mcp-system-info"],
      "env": {
        "SYSINFO_TRANSPORT": "sse",
        "SYSINFO_HOST": "localhost",
        "SYSINFO_PORT": "8001",
        "SYSINFO_MOUNT_PATH": "/mcp"
      }
    }
  }
}
```

3. **Restart Claude Desktop** to load the new server.

### Using with Claude

Once configured, you can ask Claude to:

- "What's my current CPU usage?"
- "Show me the top 10 processes using the most memory"
- "How much disk space is available?"
- "What's my system uptime?"
- "Give me a complete system overview"

## Testing

### Running Tests

```bash
# 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
```

### Test Structure

- `tests/test_config.py` - Configuration validation tests
- `tests/test_tools.py` - Tool implementation tests  
- `tests/test_resources.py` - Resource handler tests
- `tests/test_utils.py` - Utility function tests

All tests use mocked dependencies for consistent, fast execution across different environments.

## Performance Considerations

- **Caching:** Intelligent caching reduces system calls and improves response times
- **Configurable intervals:** Adjust cache TTL based on your needs
- **Lazy loading:** Temperature sensors and other optional features load only when needed
- **Async support:** Built on FastMCP for efficient async operations

## Security Features

- **Read-only operations:** No system modification capabilities
- **Sensitive data filtering:** Command-line arguments are filtered for passwords, tokens, etc.
- **Input validation:** All parameters are validated before processing
- **Error isolation:** Failures in one tool don't affect others

## Platform Support

- **macOS** - Full support including temperature sensors on supported hardware
- **Linux** - Full support with hardware-dependent sensor availability  
- **Windows** - Full support with platform-specific optimizations

## Troubleshooting

### Common Issues

1. **Permission errors:** Some system information may require elevated privileges
2. **Missing sensors:** Temperature/fan data availability varies by hardware
3. **Performance impact:** Reduce cache TTL or limit process counts for better performance

### Debug Mode

Enable debug logging for troubleshooting:
```bash
SYSINFO_LOG_LEVEL=DEBUG uv run mcp-system-info
```

### Verifying Installation

Test that tools work correctly:
```bash
uv run python -c "from system_info_mcp.tools import get_cpu_info; print(get_cpu_info())"
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run the full test suite
5. Submit a pull request

### Code Standards

- Follow PEP 8 style guidelines
- Add type hints to all functions
- Write tests for new functionality
- Update documentation as needed

## License

[Add your license information here]

## Support

[Add support information here]