What is Mcp Experiments

mcp-experiments is a project that provides an MCP (Model Context Protocol) server enabling large language models (LLMs) to execute Bash and AppleScript commands on a Mac desktop.

Use cases

Use cases include automating repetitive tasks on a Mac, executing commands based on natural language requests, and integrating LLMs with desktop environments for enhanced functionality.

How to use

To use mcp-experiments, clone the repository, set up a Python virtual environment, install the required dependencies, and configure Claude Desktop to load the MCP server for executing commands.

Key features

Key features include the ability to execute Bash and AppleScript commands, support for restricted and arbitrary execution modes, and compatibility with the Claude Desktop client.

Where to use

mcp-experiments can be used in areas such as desktop automation, command execution from LLMs, and enhancing user interaction with Mac applications.

MCP Experiments

This repository contains some MCP (Model Context Protocol) servers I’ve been playing around with for executing Bash and AppleScript commands from large language models (LLMs) on a Mac. I tested it using the Claude Desktop client.

Example Usage

Once the tool is properly configured and loaded into Claude Desktop, you can ask Claude to do new things. The tools available in restricted mode include:

• say: Could you please say “Hello World!”
• whoami: Which user am I running as?

In arbitrary execution mode (described below), you can ask Claude to perform more complicated actions.

Requirements

• macOS (Required for AppleScript tool)
• Claude Desktop, or other MCP client
• Python 3.13 or higher
• mcp package for Python
• pytest package for tests

Installation

1. Clone the repository:

   git clone .../mcp-experiments
   cd mcp-experiments
   

2. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install the required dependencies:

   pip install -r requirements.txt
   

4. Configure Claude Desktop for Mac to load the servers.

   i. Modify the configuration file located at: ~/Library/Application Support/Claude/claude_desktop_config.json.

   ii. An example configuration is provided in claude_decktop_config.example.json in this repository.

   iii. Ensure the command and args fields point to the correct Python interpreter and script path.

   iv. Ensure that MCP_EXECUTION_MODE is set to your desired safety level.

{
  "mcpServers": {
    "applescript": {
      "command": "/path/to/mcp-experiments/.venv/bin/python",
      "args": [
        "/path/to/mcp-experiments/applescript.py"
      ],
      "env": {
        "MCP_EXECUTION_MODE": "restricted"
      }
    },
    "bash": {
      "command": "/path/to/mcp-experiments/.venv/bin/python",
      "args": [
        "/path/to/mcp-experiments/bash.py"
      ],
      "env": {
        "MCP_EXECUTION_MODE": "restricted"
      }
    }
  }
}

Arbitrary Execution Mode

[!WARNING]
Setting the environment variable MCP_EXECUTION_MODE to arbitrary will allow this server to execute arbitrary code generated by the client (LLM) on your computer. This is a security concern and may result in unintended consequences. Please consider using a sandbox to play around with this mode.

TO enable arbitrary execution mode, set the environment variable MCP_EXECUTION_MODE to arbitrary. Two more tools are then exposed to the client:

• execute_bash: Runs arbitrary bash script as the current user and returns the result.
• execute_applescript: Runs arbitrary AppleScript script as the current user and returns the result.

File Structure

• applescript.py: A server script that defines the execute_applescript tool, which uses AppleScript to complete tasks.
• bash.py: A server script that defines the execute_bash tool, which uses bash to complete tasks.
• claude_desktop_config.example.json: Example configuration file for the MCP server. Yours may be located in ~/Library/Application Support/Claude.
• requirements.txt: Python dependencies for the project.
• test: Pytest unit tests for the applescript and bash tools.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Credits

This project was created by Jordan Perr-Sauer.
Github Copilot (with GPT-4o and Claude 3.5 Sonnet) was used to generate some of the content in this repository.