MCP System Info

🚀 System Information MCP Server

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

🚀 Quick Start

The System Information MCP Server provides real - time system information and metrics. You can quickly start using it through the installation steps below.

✨ Features

🛠️ Available Tools

• get_cpu_info: Retrieve CPU usage, core counts, frequency, and load average.
• get_memory_info: Get virtual and swap memory statistics.
• get_disk_info: Get disk usage information for all mounts or specific paths.
• get_network_info: Get network interface information and I/O statistics.
• get_process_list: Get running processes with sorting and filtering options.
• get_system_uptime: Get system boot time and uptime information.
• get_temperature_info: Get temperature sensors and fan speeds (when available).

📚 Available Resources

• system://overview: A comprehensive system overview with all metrics.
• system://processes: The 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 <repository-url>
   cd mcp-system-info
   

2. Install dependencies:

   uv sync
   

3. Run the server:

   uv run mcp-system-info
   

💻 Usage Examples

Basic Usage

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

Advanced Usage

The advanced usage mainly involves more complex configuration of the server, such as different transport modes and environment variable settings.

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

📚 Documentation

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

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)

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

🔧 Technical Details

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]