Content
# Dev Environment Setup (macOS)
Guide for setting up the development environment for Claude Code + MCP + Superpowers on macOS.
> **Windows Version:** [dev-environment-setup-windows](https://github.com/Afanaseva/dev-environment-setup-windows)
## Table of Contents
1. [Cursor](#1-cursor)
2. [Python](#2-python)
3. [Node.js](#3-nodejs)
4. [Claude Code](#4-claude-code)
5. [Claude Authorization](#5-claude-authorization)
6. [Homebrew](#6-homebrew)
7. [Git and GitHub CLI](#7-git-and-github-cli)
8. [MCP Plugins](#8-mcp-plugins)
9. [Superpowers Skills](#9-superpowers-skills)
10. [Environment Verification](#10-environment-verification)
11. [Automatic Installation (Prompts)](#11-automatic-installation-prompts)
## 1. Cursor
### Step 1. Download
Go to the official website: https://cursor.sh
Click **Download for Mac**.
### Step 2. Install
- Open the downloaded `.dmg`
- Drag Cursor to the **Applications** folder
- Launch Cursor from Applications
**If macOS complains:**
`System Settings → Privacy & Security → Allow Anyway`
## 2. Python
### Step 1. Verify Installation
Open in Cursor: `Terminal → New Terminal`
Type in the terminal:
```bash
python3 --version
```
Or simply ask Cursor which Python is installed.
If the version is shown (e.g., `3.11.x`) — proceed to the next section.
### Step 2. If Python is NOT installed
1. Go to the official website: https://www.python.org/downloads/mac-osx/
2. Download the latest Python 3 version
3. Install it as usual (Next → Next)
4. After installation, restart Cursor and verify again:
```bash
python3 --version
```
## 3. Node.js
Node.js is required for Claude Code.
### Installation
1. Go to: https://nodejs.org
2. Download the **LTS version** for macOS
3. Install it
### Verification
```bash
node -v
npm -v
```
Or simply ask Cursor if Node.js is installed.
## 4. Claude Code
In the Cursor terminal, type:
```bash
npm install -g @anthropic-ai/claude-code
```
Verify:
```bash
claude --version
```
If the version is displayed — everything works.
## 5. Claude Authorization
> **Use the corporate LLM-proxy `cc.sputnik.systems`.**
> VPN is **not required**, a paid Claude account is **not required** — only a GitHub account that is part of the `sputnik-systems` organization is needed.
### Steps
1. Open Cursor.
2. **CLOSE** the dialog window with Cursor (right panel) — completely.
3. Open the terminal in Cursor.
4. Run the installer — it will authorize through GitHub and configure Claude Code:
```bash
npx -p github:sputnik-asgardos/llm-proxy asgardos-setup
```
5. A short code will appear in the terminal (e.g., `WDJB-MJHT`) and a link `https://github.com/login/device`. Open the link, enter the code, and confirm.
6. Wait for the `Setup complete` message — the installer will write the proxy and token to `~/.claude/settings.json`.
7. Verify that everything works:
```bash
claude -p "which model do you use"
```
The expected response contains `glm-5.1` or `mimo` — this means the proxy is connected.
### If it didn't work
**A)** `command not found: npx` or `node --version` less than `v20` — update Node.js:
```bash
brew install node
```
And restart the terminal.
**B)** `403` / `access denied` in the browser when entering the code — the GitHub account is not in the `sputnik-systems` organization. Write to `#dev` to be added.
**C)** `claude` works but responds like a regular Claude (not GLM/MiMo) — restart the installer:
```bash
npx -p github:sputnik-asgardos/llm-proxy asgardos-setup
```
**D)** `401 unauthorized` — the token has expired, run `asgardos-setup` again.
**E)** If something remains unclear or you want a step-by-step manual path — see <https://github.com/sputnik-asgardos/llm-proxy/blob/main/CLAUDE_CODE_SETUP.md>.
## 6. Homebrew
Homebrew is a package manager for macOS.
### Verification
```bash
brew --version
```
### If not installed
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
Add to PATH (for zsh):
```bash
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc
```
Update:
```bash
brew update
```
## 7. Git and GitHub CLI
### Installation via Homebrew
```bash
brew install git gh
```
### Verification
```bash
git --version
gh --version
```
> **Note:** GitHub CLI (gh) is installed, but GitHub authorization is not required at this stage.
## 8. MCP Plugins
MCP plugins extend the capabilities of Claude Code.
### A) Playwright MCP
```bash
claude mcp add --scope user playwright -- npx -y @playwright/mcp@latest
```
Verification:
```bash
claude mcp list | grep -i playwright
```
### B) Context7 MCP
```bash
claude mcp add context7 -- npx -y @upstash/context7-mcp@latest
```
Alternative option (SSE transport):
```bash
claude mcp add --transport sse context7 https://mcp.context7.com/sse
```
Verification:
```bash
claude mcp list | grep -i context7
```
### C) Serena MCP (universal LSP)
Requires `uv`:
```bash
brew install uv
```
Install Serena:
```bash
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)"
```
Verification:
```bash
claude mcp list | grep -i serena
```
### D) Cartographer (codebase map) — optional
Cartographer creates a complete map of the project in the `docs/CODEBASE_MAP.md` file. When starting a new Claude Code session, it reads this map instead of re-walking through the entire project — this **significantly saves tokens** on large codebases.
Repository: https://github.com/kingbootoshi/cartographer
Requires `tiktoken`:
```bash
pip install tiktoken
```
Installation:
In interactive Claude Code mode (`claude`):
```
/plugin marketplace add kingbootoshi/cartographer
/plugin install cartographer
```
Usage:
```
/cartographer
```
> **When needed:** for projects with 20+ files. In small projects, Claude can quickly understand the structure.
Verification:
```bash
# After running /cartographer, the file should appear:
ls docs/CODEBASE_MAP.md
```
## 9. Superpowers Skills
Superpowers is a set of skills to improve Claude Code performance.
Repository: https://github.com/obra/superpowers
### Installation
Run interactive `claude` and execute:
```
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
```
### Update
```
/plugin update superpowers
```
## 10. Environment Verification
### Checklist
| # | Component | Verification Command |
|---|-----------|------------------|
| 1 | VPN | `curl -s https://ifconfig.me` (verify IP) |
| 2 | Cursor | Should be open |
| 3 | Python | `python3 --version` |
| 4 | Node.js | `node -v && npm -v` |
| 5 | Homebrew | `brew --version` |
| 6 | Git | `git --version` |
| 7 | GitHub CLI | `gh --version` |
| 8 | Claude CLI | `claude --version` |
| 9 | Claude Authorization | `claude auth status` |
| 10 | MCP Plugins | `claude mcp list` |
| 11 | Superpowers | Verify in interactive mode |
### Quick Verification
You can ask Claude to verify the environment by sending it this request:
```
Verify my environment for work. I need to check and output the status (installed / not installed) for the following items:
1. VPN connection
2. Cursor
3. Python
4. Node.js
5. Homebrew
6. Git
7. GitHub CLI (gh)
8. Claude CLI
9. Claude account presence (authorization)
10. Installed plugins:
– Context7
– Playwright
– Serena (universal LSP)
11. Configured skills from the link https://github.com/obra/superpowers
```
## 11. Automatic Installation (Prompts)
Installation is divided into 2 stages:
- **Prompt 1** — for Cursor (installation of everything up to MCP plugins)
- **Prompt 2** — for Claude (installation of Superpowers + final verification)
### Prompt 1: For Cursor
Copy and send this prompt to the Cursor chat:
```
You are a dev environment installer. You work in the terminal on the current machine.
Goal: prepare the basic environment for Claude Code + MCP:
- VPN (check, if necessary, ask to enable manually)
- Homebrew
- Python
- Node.js
- Git
- GitHub CLI (gh) — ONLY install, DO NOT log in to GitHub
- Claude Code/CLI (claude)
- Authorization in Claude
- MCP plugins: Context7, Playwright, Serena
Rules:
1) First, do diagnostics and output a brief plan (what is already there / what is not).
2) Then perform the installation/configuration step by step.
3) Before changing configs — make backups of files.
4) Where manual actions are required (VPN/login in the browser) — stop and ask me to perform the action.
STEP 0 — Diagnostics
- Determine OS/shell:
- uname -a
- sw_vers (if macOS)
- echo $SHELL
- Check VPN "in fact":
- ifconfig | egrep "utun|ppp|tun" || true
- curl -s https://ifconfig.me ; echo
If VPN does not look connected — ask me to enable VPN manually.
STEP 1 — Homebrew
- If brew is not available: install Homebrew in the official way and add to PATH for zsh.
- Note: if it requests sudo — it is the password of the current macOS user.
- Then: brew update
STEP 2 — Basic packages
- brew install python node git gh uv
STEP 3 — Claude Code
- npm install -g @anthropic-ai/claude-code
- Check: claude --version
- Authorization: claude auth login
(the browser will open; wait for completion)
STEP 4 — MCP plugins
A) Playwright MCP:
- claude mcp add --scope user playwright -- npx -y @playwright/mcp@latest
B) Context7 MCP:
- claude mcp add context7 -- npx -y @upstash/context7-mcp@latest
C) Serena MCP:
- claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)"
Check all plugins: claude mcp list
STEP 5 — Intermediate report
Output status:
- VPN: connected / not connected
- Installed: brew, python3, node/npm, git, gh, uv, claude
- Claude authorization: result of claude auth status
- MCP plugins: output of claude mcp list
After that, write:
"Basic installation completed. Now run the command `claude` in the terminal and send it Prompt 2 to install Superpowers."
```
---
### Prompt 2: For Claude
After completing Prompt 1, run `claude` in the terminal and send this prompt:
```
Install Superpowers and check the environment.
STEP 1 — Superpowers Skills
Perform commands:
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace
STEP 2 — Final environment check
Check and output status (installed / not installed) for all items:
1. VPN connection (curl -s https://ifconfig.me)
2. Python (python3 --version)
3. Node.js (node -v && npm -v)
4. Homebrew (brew --version)
5. Git (git --version)
6. GitHub CLI (gh --version)
7. Claude CLI (claude --version)
8. Claude authorization (claude auth status)
9. MCP plugins (claude mcp list):
- Context7
- Playwright
- Serena
10. Superpowers Skills — installed?
Output the final table with statuses.
```
---
## Troubleshooting
### VPN not working
- Check that the VPN client is running and connected
- Check IP: `curl -s https://ifconfig.me`
### Claude not authorized
- Make sure VPN is enabled
- Try `/login` in interactive mode claude
### Homebrew not found after installation
Add to PATH:
```bash
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc
```
### MCP plugin not working
Restart Claude Code and check:
```bash
claude mcp list
```
