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:

uvx install mcp-system-info

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

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

Development Installation

For local development:

1. Clone the repository:

git clone 
   cd mcp-system-info

2. Install dependencies:

uv sync

3. Run the server:

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:

uv sync --dev

2. Run tests:

uv run pytest

3. Run tests with coverage:

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

4. Format code:

uv run black src/ tests/

5. Lint code:

uv run ruff check src/ tests/

6. Type checking:

uv run mypy src/

Building and Publishing

Build the Package

# 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:

# 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

# 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)

# 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. Streamable HTTP

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

Complete Example:

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

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

Get Process List

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

Get Disk Information

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

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

Resource Usage

System Overview

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

Process List Resource

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

Integration with Claude Desktop

Adding to Claude Desktop

1. Locate your Claude Desktop config file:

2. Add the MCP server configuration:

Using uvx (Recommended)

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

For Local Development

{
  "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)

{
  "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

# 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:

SYSINFO_LOG_LEVEL=DEBUG uv run mcp-system-info

Verifying Installation

Test that tools work correctly:

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]