SETUP_MACOS.md•3.43 kB
# Aseprite MCP Setup Instructions for macOS
## Prerequisites
1. **Aseprite**: Must be installed. You can either:
- Purchase from [Aseprite.org](https://www.aseprite.org/)
- Build from source (see below)
2. **Python 3.10+**: The project requires Python 3.10 or higher
- macOS often comes with Python 3.9, which is not compatible
- Use `uv` (recommended) to manage Python versions automatically
## Setup with UV (Recommended)
### 1. Install UV
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Add to your PATH:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
### 2. Clone and Setup
```bash
# Clone the repository
git clone https://github.com/your-username/AsepriteMCP.git
cd AsepriteMCP
# Create virtual environment with Python 3.13
uv venv
# Activate virtual environment
source .venv/bin/activate
# Install dependencies
uv pip install -e .
```
### 3. Configure Aseprite Path
Create a `.env` file:
```bash
echo "ASEPRITE_PATH=/path/to/your/aseprite" > .env
```
Common Aseprite paths:
- **Purchased**: `/Applications/Aseprite.app/Contents/MacOS/aseprite`
- **Built from source**: `~/aseprite-build/aseprite/build/bin/aseprite`
### 4. Configure Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"aseprite": {
"command": "/path/to/AsepriteMCP/.venv/bin/python",
"args": ["-m", "aseprite_mcp"],
"cwd": "/path/to/AsepriteMCP",
"env": {
"ASEPRITE_PATH": "/path/to/your/aseprite",
"PYTHONPATH": "/path/to/AsepriteMCP"
}
}
}
}
```
### 5. Restart Claude Desktop
The MCP server should now be available in Claude Desktop.
## Building Aseprite from Source (Optional)
If you don't have Aseprite, you can build it from source:
```bash
# Install dependencies
brew install cmake ninja
# Clone Aseprite
git clone --recursive https://github.com/aseprite/aseprite.git
cd aseprite
# Download Skia
mkdir -p build/deps
cd build/deps
curl -LO https://github.com/aseprite/skia/releases/download/m124-4314887985/Skia-macOS-Release-arm64.zip
unzip Skia-macOS-Release-arm64.zip
cd ../..
# Build
mkdir build
cd build
cmake \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DCMAKE_OSX_ARCHITECTURES=arm64 \
-DCMAKE_OSX_DEPLOYMENT_TARGET=10.9 \
-DLAF_BACKEND=skia \
-DSKIA_DIR=$PWD/deps/skia \
-DSKIA_LIBRARY_DIR=$PWD/deps/skia/out/Release-arm64 \
-G Ninja \
..
ninja aseprite
# The binary will be at: build/bin/aseprite
```
## Troubleshooting
### Python Version Issues
If you see errors about Python version:
```
ERROR: Could not find a version that satisfies the requirement mcp>=1.6.0
```
This means you're using Python < 3.10. Use UV to create a virtual environment with Python 3.13.
### Missing exceptions.py
If you see:
```
ModuleNotFoundError: No module named 'aseprite_mcp.core.exceptions'
```
Make sure you have the latest version with the exceptions.py file.
### Aseprite Not Found
If you see errors about Aseprite not being found:
1. Check your `.env` file has the correct path
2. Test the path: `/path/to/aseprite --version`
3. Make sure the path in Claude Desktop config matches
## Testing the Installation
Once configured, you can test in Claude Desktop:
- "Create a new 320x240 canvas with Aseprite"
- "Draw a red rectangle on the canvas"
For development, you can test locally:
```bash
cd AsepriteMCP
source .venv/bin/activate
python -m aseprite_mcp
```