# MCP Experiments

[![Tests](https://github.com/jordanperr/mcp-experiments/actions/workflows/test.yml/badge.svg)](https://github.com/jordanperr/mcp-experiments/actions/workflows/test.yml)

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](https://claude.ai/download) 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](https://claude.ai/download), or other MCP client
- Python 3.13 or higher
- `mcp` package for Python
- `pytest` package for tests

## Installation

1. Clone the repository:
   ```sh
   git clone .../mcp-experiments
   cd mcp-experiments
   ```

2. Create and activate a virtual environment:
   ```sh
   python3 -m venv .venv
   source .venv/bin/activate
   ```

3. Install the required dependencies:
   ```sh
   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.

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