TRAA MCP Server: A Powerful Screen Capture MCP Server

Project repository traa-mcp, Your stars will be my greatest motivation for further improvements. Project Introduction TRAA MCP Server is a screen capture server based on the Model Context Protocol (MCP) and traa. It provides system screen and window enumeration capabilities, as well as screenshot capture functionality. Through the MCP protocol, the server can communicate with clients, supporting both standard input/output (stdio) and Server-Sent Events (SSE) transmission methods. Usage in Claude Desktop Core Features 1. Screen and Window Source Enumeration sources = enum_screen_sources() for source in sources: print(f"ID: {source.id}") print(f"Title: {source.title}") print(f"Type: {'Window' if source.is_window else 'Display'}") print(f"Position: {source.rect}") # (left, top, right, bottom) This feature can: List all available displays in the system List all available windows in the system Provide detailed information for each source, including ID, title, type, and position information 2. Screen Capture The project offers two screenshot methods: 2.1 Direct Image Data Retrieval image = create_snapshot( source_id=1, # Screen source ID size=(1920, 1080) # Desired size ) This method returns an MCP Image object, suitable for scenarios requiring direct image data processing. 2.2 Save to File save_snapshot( source_id=1, # Screen source ID size=(1920, 1080), # Desired size file_path="screenshot.jpeg", # Save path quality=80, # Image quality (1-100) format="jpeg" # Image format ) This method directly saves the screenshot as a file, supporting: Automatic directory creation Configurable image quality Support for JPEG and PNG formats Technical Implementation 1. Architecture Design The project adopts a modular design, mainly containing the following components: enum_screen_sources: Enumerate screen sources create_snapshot: Create screenshots save_snapshot: Save screenshots _create_snapshot: Internal implementation function 2. Error Handling The project implements a comprehensive error handling mechanism: try: result = traa.create_snapshot(source_id, size) except ValueError as e: # Parameter validation error raise e except traa.Error as e: # TRAA-related error raise RuntimeError(f"Failed to create snapshot: {e}") except Exception as e: # Other unexpected errors raise RuntimeError(f"Unexpected error: {e}") 3. Image Processing Support for RGBA and RGB format conversion Automatic image size optimization Configurable image quality settings Usage Guide 1. Install Dependencies pip install mcp>=1.0.0 anyio>=4.5 traa>=0.1.5 pillow>=11.1.0 Recommended to use uv for dependency installation: uv sync 2. Start the Server Supports two running modes: stdio mode (default): uv run traa_mcp_server SSE mode: uv run traa_mcp_server-sse --port 3001 3. Use the Client uv run traa_mcp_client 4. Complete Example # 1. Enumerate all screen sources sources = enum_screen_sources() for source in sources: print(f"Found screen source: {source.title}") # 2. Capture screenshot of the first screen source if sources: # Get image data image = create_snapshot(sources[0].id, (1920, 1080)) # Save as file save_snapshot( sources[0].id, (1920, 1080), "screenshot.jpeg", quality=80, format="jpeg" ) Best Practices Image Format Selection JPEG: Suitable for screenshots with many colors, smaller file size PNG: Suitable for screenshots with text or requiring transparency, better quality Performance Optimization Default to JPEG format with quality set to 60 to keep file size under 1MB Adjust quality settings as needed Error Handling Always check return values Use try-except to handle potential exceptions Review detailed error messages for troubleshooting Summary TRAA MCP Server provides a powerful and flexible screen capture solution. Its modular design, comprehensive error handling, and rich features make it an ideal choice for various screen capture needs. Whether you need simple screenshot functionality or complex image processing, this project can meet your requirements. References Model Context Protocol (MCP) Pillow Documentation TRAA Documentation

May 1, 2025 - 15:56

TRAA MCP Server: A Powerful Screen Capture MCP Server

Project repository traa-mcp, Your stars will be my greatest motivation for further improvements.

Project Introduction

TRAA MCP Server is a screen capture server based on the Model Context Protocol (MCP) and traa. It provides system screen and window enumeration capabilities, as well as screenshot capture functionality. Through the MCP protocol, the server can communicate with clients, supporting both standard input/output (stdio) and Server-Sent Events (SSE) transmission methods.

Usage in Claude Desktop

Core Features

1. Screen and Window Source Enumeration

sources = enum_screen_sources()
for source in sources:
    print(f"ID: {source.id}")
    print(f"Title: {source.title}")
    print(f"Type: {'Window' if source.is_window else 'Display'}")
    print(f"Position: {source.rect}")  # (left, top, right, bottom)

This feature can:

List all available displays in the system
List all available windows in the system
Provide detailed information for each source, including ID, title, type, and position information

2. Screen Capture

The project offers two screenshot methods:

2.1 Direct Image Data Retrieval

image = create_snapshot(
    source_id=1,           # Screen source ID
    size=(1920, 1080)      # Desired size
)

This method returns an MCP Image object, suitable for scenarios requiring direct image data processing.

2.2 Save to File

save_snapshot(
    source_id=1,           # Screen source ID
    size=(1920, 1080),     # Desired size
    file_path="screenshot.jpeg",  # Save path
    quality=80,            # Image quality (1-100)
    format="jpeg"          # Image format
)

This method directly saves the screenshot as a file, supporting:

Automatic directory creation
Configurable image quality
Support for JPEG and PNG formats

Technical Implementation

1. Architecture Design

The project adopts a modular design, mainly containing the following components:

enum_screen_sources: Enumerate screen sources
create_snapshot: Create screenshots
save_snapshot: Save screenshots
_create_snapshot: Internal implementation function

2. Error Handling

The project implements a comprehensive error handling mechanism:

try:
    result = traa.create_snapshot(source_id, size)
except ValueError as e:
    # Parameter validation error
    raise e
except traa.Error as e:
    # TRAA-related error
    raise RuntimeError(f"Failed to create snapshot: {e}")
except Exception as e:
    # Other unexpected errors
    raise RuntimeError(f"Unexpected error: {e}")

3. Image Processing

Support for RGBA and RGB format conversion
Automatic image size optimization
Configurable image quality settings

Usage Guide

1. Install Dependencies

pip install mcp>=1.0.0 anyio>=4.5 traa>=0.1.5 pillow>=11.1.0

Recommended to use uv for dependency installation:

uv sync

2. Start the Server

Supports two running modes:

stdio mode (default):

uv run traa_mcp_server

SSE mode:

uv run traa_mcp_server-sse --port 3001

3. Use the Client

uv run traa_mcp_client

4. Complete Example

# 1. Enumerate all screen sources
sources = enum_screen_sources()
for source in sources:
    print(f"Found screen source: {source.title}")

# 2. Capture screenshot of the first screen source
if sources:
    # Get image data
    image = create_snapshot(sources[0].id, (1920, 1080))

    # Save as file
    save_snapshot(
        sources[0].id,
        (1920, 1080),
        "screenshot.jpeg",
        quality=80,
        format="jpeg"
    )

Best Practices

Image Format Selection
- JPEG: Suitable for screenshots with many colors, smaller file size
- PNG: Suitable for screenshots with text or requiring transparency, better quality
Performance Optimization
- Default to JPEG format with quality set to 60 to keep file size under 1MB
- Adjust quality settings as needed
Error Handling
- Always check return values
- Use try-except to handle potential exceptions
- Review detailed error messages for troubleshooting

Summary

TRAA MCP Server provides a powerful and flexible screen capture solution. Its modular design, comprehensive error handling, and rich features make it an ideal choice for various screen capture needs. Whether you need simple screenshot functionality or complex image processing, this project can meet your requirements.