Tutorials

1. What is xMCP?

 

xMCP is a Model Context Protocol (MCP) server for macOS that enables AI assistants to control and interact with your Mac. It acts as a bridge between AI assistants like Claude and your macOS system, allowing them to perform tasks such as reading files, executing commands, controlling applications, and accessing system resources.

 

The Model Context Protocol is an open protocol developed by Anthropic that standardizes how AI assistants connect to data sources and tools. xMCP implements this protocol to give AI assistants powerful control over your macOS system in a secure and monitored way.

 

Key Features:

- File system operations (read, write, create, delete, search)

- System command execution

- Application control via AppleScript

- Network operations (HTTP requests, DNS resolution, port checking)

- System resource monitoring (CPU, memory, disk usage)

- File monitoring and watching

- Advanced file operations (diff, archive, sync, compress)

- Screenshot capture

- Clipboard management

- And much more

 

 

2. Getting Started

 

When you first launch xMCP, you will see the main Dashboard window. The app also creates a menu bar icon that stays visible even when the window is closed.

 

First-Time Setup:

1. Launch xMCP from your Applications folder

2. The Dashboard window will appear showing the Status view

3. You may see a trial status badge if you are using the trial version

4. Check the Settings section to configure your preferences

 

Permissions:

xMCP may request certain permissions on first launch:

- Accessibility permission: Required for app automation features

- Automation permission: Prompts when needed for controlling other applications

 

If you see permission requests, grant them to enable all features. You can check and manage permissions in the Settings section.

 

 

3. Starting the Server

 

Before AI assistants can use xMCP, you need to start the server.

 

To start the server:

1. Open the Dashboard window (click the menu bar icon if the window is hidden)

2. In the Status view, you will see a large button labeled "Start Server"

3. Click the "Start Server" button

4. The button will change to "Stop Server" and show a green indicator when running

5. The status indicator in the sidebar will show a green circle when running

 

Auto-Start Option:

You can enable the server to start automatically when you launch xMCP:

1. Go to Settings in the sidebar

2. Under "Server Configuration", enable "Auto-start server on launch"

3. The server will now start automatically each time you open xMCP

 

Stopping the Server:

To stop the server, click the "Stop Server" button in the Status view. The server will stop accepting new connections and tool requests.

 

 

4. Connecting AI Assistants

 

Once the server is running, you need to configure your AI assistant to connect to xMCP.

 

Local Access (Same Mac):

For Claude Desktop on the same Mac:

 

1. Make sure xMCP server is running

2. Open Claude Desktop

3. Edit the Claude Desktop configuration file:

   File location: ~/Library/Application Support/Claude/claude_desktop_config.json

 

4. Add the following configuration:

 

{

  "mcpServers": {

    "xmcp": {

      "command": "/Applications/xMCP.app/Contents/MacOS/xMCP"

    }

  }

}

 

5. Save the file and restart Claude Desktop

6. Claude Desktop will now have access to all xMCP tools

 

Note: The exact path may vary depending on where you installed xMCP. If xMCP is not in the Applications folder, adjust the path accordingly.

 

Remote Access via SSH:

To allow a remote AI server to control your Mac:

 

1. Enable Remote Login on your Mac:

   System Settings > General > Sharing > Remote Login

   Enable for specific users only (recommended)

 

2. Configure SSH security (highly recommended):

   - Use SSH keys only, disable password authentication

   - Whitelist the AI server IP address in SSH configuration

   - Enable macOS Firewall

   - Consider using a VPN for private network access

 

3. From the remote AI server, connect via SSH:

   ssh your_username@your_mac_ip "/Applications/xMCP.app/Contents/MacOS/xMCP"

 

Security Warning: Remote access gives full control of your Mac to the AI server. Only enable this for trusted AI servers. Monitor the Activity Log regularly to see what actions are being performed.

 

 

5. Understanding the Dashboard

 

The Dashboard is the main interface of xMCP. It has several sections accessible from the sidebar:

 

Status View:

- Shows the current server status (running or stopped)

- Large start/stop button for server control

- Status cards showing server status, connection count, and total requests

- Recent activity log showing the last 10 activities

- Trial or license status information

 

Statistics View:

- Detailed statistics about server usage

- Session information

- Tool usage statistics

- Connection history

- Performance metrics

 

Activity Log View:

- Complete log of all server activities

- Filterable and searchable log entries

- Export functionality to save logs

- Clear button to reset the log

- Shows requests, tool calls, successes, and errors

 

Functions View:

- Browse all available tools, resources, and prompts

- Organized by categories

- Search functionality to find specific tools

- Expandable cards showing tool parameters and descriptions

- Three tabs: Tools, Resources, and Prompts

 

Settings View:

- Server configuration options

- Security settings

- License management

- Permission management

- System integration options

 

Getting Started View:

- Documentation and setup instructions

- Connection examples

- Security guidelines

 

Examples View:

- Common use cases

- Example commands and tool calls

- Practical examples for different scenarios

 

 

6. Available Tools and Features

 

xMCP provides a wide range of tools organized into categories:

 

File System Tools:

- read_file: Read the contents of any file

- write_file: Write content to a file

- list_directory: List files and folders in a directory

- create_directory: Create new directories

- delete_file: Delete files or directories

- move_file: Move or rename files

- copy_file: Copy files or directories

- search_files: Search for files matching a pattern

 

File Monitoring Tools:

- watch_directory: Monitor a directory for changes

- watch_file: Monitor a specific file for changes

- wait_for_file: Wait for a file to appear or change

 

Network Tools:

- http_request: Make HTTP requests to web servers

- resolve_dns: Resolve domain names to IP addresses

- check_port: Check if a network port is open

- download_file: Download files from the internet

 

System Tools:

- execute_command: Run shell commands

- get_clipboard: Read clipboard contents

- set_clipboard: Set clipboard contents

- capture_screenshot: Take a screenshot

- get_system_info: Get system information

- send_notification: Send macOS notifications

 

System Resource Tools:

- get_memory_usage: Check memory usage

- get_cpu_usage: Check CPU usage

- get_disk_usage: Check disk space

- get_network_info: Get network interface information

 

App Control Tools:

- list_running_apps: List all running applications

- launch_app: Launch an application

- quit_app: Quit an application

- execute_applescript: Execute AppleScript commands

 

Advanced File Tools:

- file_diff: Compare two files and show differences

- archive_files: Create archives (zip, tar, etc.)

- sync_directories: Synchronize two directories

- compress_file: Compress files

 

Resources:

xMCP also provides resources that can be accessed by AI assistants:

- System resources: Information about the macOS system

- Server resources: Information about the xMCP server itself

 

Prompts:

Pre-built prompts are available for common tasks:

- Analysis prompts for code review and analysis

- System prompts for optimization and backup

- Security prompts for audits and security checks

- Network prompts for API testing

- File operation prompts for file management tasks

- Development prompts for build and version control

- Enterprise prompts for resource monitoring and disaster recovery

 

To explore all available tools:

1. Go to Functions in the sidebar

2. Use the tabs to switch between Tools, Resources, and Prompts

3. Use the category filter to narrow down the list

4. Use the search box to find specific tools

5. Click on any tool card to expand and see detailed parameters

 

 

7. Settings and Configuration

 

The Settings view allows you to configure xMCP to suit your needs:

 

Server Configuration:

- Auto-start server on launch: Automatically start the server when xMCP opens

- Show notifications: Enable macOS notifications for server events

- Log level: Control how much information is logged (Debug, Info, Warning, Error)

- Max log entries: Set the maximum number of log entries to keep

- Enable tool logging: Log detailed information about tool executions

 

Security Settings:

- Require confirmation for dangerous tools: Ask for confirmation before executing potentially dangerous operations

- Command timeout: Set how long commands can run before timing out (5-300 seconds)

 

Note: All tools run with the permissions of the xMCP application. Only connect trusted AI clients. All activity is logged.

 

License Management:

- View current license status

- Enter license key if you have purchased a license

- Deactivate license if needed

- View trial status and remaining trial starts

- Link to the store to purchase a license

 

Permissions:

- View accessibility permission status

- Grant accessibility permission if needed

- Refresh permission status

 

System Integration:

- Launch at login: Automatically start xMCP when you log in to your Mac

 

 

8. Menu Bar Integration

 

xMCP adds an icon to your menu bar that provides quick access to key features:

 

Menu Bar Icon:

- Shows a server icon indicating xMCP is running

- Always visible even when the Dashboard window is closed

- Click to open the menu

 

Menu Bar Menu:

The menu provides quick access to:

- Current server status (Running or Stopped)

- Connection count

- Total requests count

- Start/Stop Server option

- Show Dashboard

- Show Statistics

- Show Activity Log

- Recent Activity (last 5 entries)

- Settings

- Quit

 

Using the Menu Bar:

- Click the menu bar icon to see the current status

- Use "Show Dashboard" to open or bring forward the main window

- Use "Start Server" or "Stop Server" to control the server

- Check recent activity without opening the full Dashboard

 

 

9. Activity Log and Statistics

 

Activity Log:

The Activity Log shows all server activity in real-time:

 

Log Entry Types:

- Info: General information messages

- Request: MCP protocol requests received

- Tool Call: Tools being executed

- Success: Successful tool executions

- Error: Errors and failures

 

Using the Activity Log:

1. Go to Activity Log in the sidebar

2. View all log entries in chronological order (newest first)

3. Use the search box to filter logs by keywords

4. Click "Export" to save logs to a file or copy to clipboard

5. Click "Clear" to remove all log entries

 

Why Monitor the Activity Log:

- See what the AI assistant is doing in real-time

- Debug issues when tools fail

- Monitor for unexpected or suspicious activity

- Track which tools are being used most frequently

 

Statistics:

The Statistics view provides detailed metrics:

 

Available Statistics:

- Total server sessions

- Total requests received

- Total tool calls executed

- Success and error rates

- Most used tools

- Connection history

- Performance metrics

- Session duration

 

Using Statistics:

1. Go to Statistics in the sidebar

2. View comprehensive statistics about server usage

3. Analyze tool usage patterns

4. Monitor performance over time

 

 

10. Troubleshooting

 

Common Issues and Solutions:

 

Server Won't Start:

- Check if your trial has expired. Go to Settings to enter a license

- Check the Activity Log for error messages

- Make sure you have granted necessary permissions

- Try quitting and restarting xMCP

 

AI Assistant Can't Connect:

- Make sure the server is running (check the Status view)

- Verify the configuration file path is correct

- Check that the xMCP app path in the configuration matches your installation

- Restart both xMCP and your AI assistant

- Check the Activity Log for connection errors

 

Tools Not Working:

- Check the Activity Log to see what errors are occurring

- Verify you have granted necessary permissions (especially Accessibility)

- Check Settings to ensure tool logging is enabled for debugging

- Some tools may require specific permissions or file access

 

Permission Issues:

- Go to Settings > Permissions

- Click "Grant Accessibility Permission" if needed

- This will open System Settings where you can enable the permission

- Restart xMCP after granting permissions

 

High CPU or Memory Usage:

- Check the Activity Log for excessive tool calls

- Review Statistics to see which tools are being used

- Consider setting a command timeout in Settings

- Monitor system resources using the built-in system resource tools

 

Menu Bar Icon Missing:

- The menu bar icon should appear automatically

- If missing, quit and restart xMCP

- Check System Settings > Control Center > Menu Bar to ensure xMCP is allowed

 

Getting More Help:

- Check the "Getting Started" section in the Dashboard

- Review the Examples section for common use cases

- Visit the support website for FAQ and additional documentation

- Submit a bug report or feature request through the Help menu

 

 

11. Security Considerations

 

xMCP is a powerful tool that gives AI assistants extensive control over your Mac. It is important to understand and follow security best practices:

 

Key Security Points:

1. xMCP is NOT sandboxed and has extensive system permissions

2. Only connect trusted AI clients

3. All activity is logged and can be monitored

4. Review the Activity Log regularly

5. Use security settings to require confirmations for dangerous operations

 

Best Practices:

- Only connect AI assistants you trust

- Monitor the Activity Log regularly to see what actions are being performed

- Use the "Require confirmation for dangerous tools" setting in Security

- Set appropriate command timeouts to prevent runaway processes

- For remote access, use SSH keys only, not passwords

- Whitelist specific IP addresses for remote access

- Enable macOS Firewall

- Consider using a VPN for remote access

- Keep xMCP updated to the latest version

- Review your license status and ensure it is valid

 

What xMCP Can Do:

xMCP can:

- Read and write any file you have access to

- Execute system commands

- Control applications

- Access system resources

- Make network requests

- Take screenshots

- Access clipboard contents

- And much more

 

This makes xMCP very powerful but also means you should only use it with trusted AI assistants. Always monitor the Activity Log to see what actions are being performed.

 

 

Conclusion

 

This tutorial has covered the basics of using xMCP. You should now be able to:

- Start and stop the server

- Connect AI assistants to xMCP

- Navigate the Dashboard

- Understand available tools and features

- Configure settings

- Monitor activity and statistics

- Troubleshoot common issues

- Follow security best practices

 

For more advanced usage, explore the Examples section in the Dashboard and experiment with different tools. Remember to always monitor the Activity Log and follow security best practices.

 

Happy automating with xMCP!