Install MCP Server Mac: Complete Setup Guide

Install MCP server Mac is the work of putting a Model Context Protocol server on your laptop and registering it with a client. The client is Claude Code, Cursor, VS Code, Codex, or Zed. The server is a local binary, a remote HTTP URL, or a connector that talks to a Mac app on 127.0.0.1.

The common mistake is pasting JSON from a blog and then asking why the tool list is empty. JSON is a pointer. Something still has to run.

If you need the primer, start with what an MCP server is and MCP tools. Cursor-specific files live in Cursor MCP.

How do I install MCP server Mac for Claude Code?

Install the client first. claude in a terminal should work. If it does not, stop. Fix the CLI before you touch MCP.

Pick a server you will actually call this week. Docs, issues, or a screen connector. Do not install twelve.

For a remote HTTP server, from a normal terminal:

claude mcp add --transport http --scope user docs https://code.claude.com/docs/mcp

For a local stdio server that ships as a binary:

claude mcp add --scope user pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp"

Never claude mcp add pinvari. That form errors.

Flags before the name. Command after --. --scope user if you want every repo.

Start a new claude session. Run /mcp. Green is the only proof.

User scope writes ~/.claude.json. Project scope writes .mcp.json at the repo root. Local scope hides the server in the current project path. There is no ~/.claude/mcp.json.

How do I install MCP server Mac for Cursor?

Cursor stores MCP config in its own JSON, not in ~/.claude.json. Mixing those files is the second most common mistake.

Use the in-app MCP panel when it exists. Or edit the file Cursor's current docs name (it has moved more than once; trust the in-app path over a 2025 gist).

Restart Cursor or reload the MCP list. A stale window keeps a stale list.

If PinVari is the server, prefer PinVari → Connect → Cursor. The app writes the path it actually installed under ~/.pinvari/mcp/pinvari-mcp.

The connector talks to the app on 127.0.0.1:3402. The app must be running. Cursor cannot launch it for you.

Cursor MCP is the deeper file-shape note. This page stays on the Mac install loop.

Claude Code

Type: CLI client

Config: claude mcp add, ~/.claude.json or .mcp.json

Proof: /mcp green

Cursor

Type: editor client

Config: Cursor MCP panel / mcp.json

Proof: tools visible in the agent panel

PinVari connector

Type: local stdio plus Mac app

Config: one-click Connect, or the add line with a path

Proof: pinvari_next_instruction appears and returns a capture

What mistakes show up when you install MCP server Mac?

No Node, no Python, no uv, no binary. Many community servers assume npx or uvx. Run the command in Terminal.app first. Read stderr. Then paste it into a client.

Sandbox and notarization. A random GitHub server that wants full disk access is a trust decision. Prefer signed apps for anything that can see the screen.

Port fights. Two copies of a server bound to the same port will fail in boring ways. Screen connectors that expect 127.0.0.1:3402 need that port free.

Project scope in the wrong repo. You committed .mcp.json in a playground. The real app repo has nothing.

Secrets in JSON. Do not commit API keys. Use env vars. Claude Code expands ${VAR} in project files.

Assuming MCP equals screen context. A GitHub MCP server files issues. It does not know which button you circled. A screenshot MCP server sends pixels. A named-element server sends role, label, frame, and confidence.

Installing as root. Do not. User-level install. User-level scope.

How do I install a screen MCP server on a Mac?

Download PinVari from pinvari.com as a notarized Developer-ID DMG. It is not the Mac App Store sandbox. That sandbox forbids the global hotkey CGEventTap plus reading other apps' AXUIElement.

macOS 14+ (Sonoma), Apple Silicon and Intel. Open the app. Grant Accessibility when asked. Leave it running.

Hold ⌥⌘A and circle a control to confirm capture works before you touch MCP. ⌥⌘V is voice-only. ⌥⌘P pauses on a scrolling page.

Then connect: PinVari → Connect → Claude Code / Cursor / VS Code / Codex. Or the claude mcp add --scope user line above.

In the client, call pinvari_next_instruction. You should get the circled region, the resolved element, the spoken line, and a crop. pinvari_health is the cheap ping.

Transcription (whisper.cpp) and OCR stay on-device. Nothing is uploaded by default. You bring your own agent.

Price is a one-time $39 launch licence. Team seats $29. No subscription for the core app.

If that is the server you wanted, the pricing page is the licence. Official tool docs sit at pinvari.com/mcp.

Launch the app, then the client. Reverse that and you will reinstall Node for no reason.

Jam.dev remains a browser-only capture habit. Marker.io is $39+ / month for website pins. CleanShot X is still pixels.

How do I verify an MCP server on a Mac after install?

Verification is a ladder. Skip a rung and you will reinstall the wrong thing.

First, the command runs in Terminal.app. If npx or the vendor binary prints an error, the client is not the problem.

Second, the client config points at that exact command and cwd. A missing env key is enough to fail after a green-looking add.

Third, you restart the client. Claude Code needs a new session. Cursor needs a reload of the MCP list.

Fourth, you call a cheap tool. pinvari_health or the vendor's ping. A tool list that renders is not the same as a tool that returns.

Fifth, you call a real tool on a real object. For a screen server, circle a control you can see. For GitHub, read an issue you own. For docs, fetch a page you know.

If step five fails and step four works, the problem is auth or scope, not install. Do not delete the config.

If Accessibility or Screen Recording prompts appear mid-tool, grant them to the capture app. Then recircle. A client running in the terminal does not inherit those grants automatically.

Keep a note of the Mac user you installed as. A second macOS user will not see your ~/.claude.json or ~/.pinvari.

What should I install first if I am MCP-curious on a Mac?

Install one client you already work in. If that is Claude Code, stop there. If that is Cursor, stop there.

Install one server that maps to a job you do this week. Docs, issues, or screen. Not all three.

Confirm /mcp or the Cursor panel. Call one tool. Then stop installing.

Curiosity does not require a fleet. Ten community servers will teach you nothing except how to debug PATH.

If the job is "tell the agent which button," install a named-element connector, not a second GitHub server. You already have a browser.

If the job is "file the issue," install the tracker server or use the Mac app's Linear / GitHub export. Do not do both on day one.

Uninstall is part of install. claude mcp remove <name> and delete the project file if you were experimenting. Leftover red servers train you to ignore /mcp.

FAQ

What does install MCP server Mac mean if I only use Cursor?

It means the server command or URL is in Cursor's MCP config and the agent can see the tools. Claude's ~/.claude.json will not help Cursor.

Do I need Homebrew?

No, not for a notarized Mac app with its own connector. Yes, often, for community servers that expect uv or node. Install the runtime the server's README names, then run the command naked in Terminal.

Where do local MCP servers listen?

It depends on the server. Many stdio servers listen on no port. They speak over stdin. PinVari's connector talks to the app on 127.0.0.1:3402. Remote servers are HTTPS URLs.

Why is the server green but the tool fails?

Auth, a missing env var, or the backing app quit after handshake. Re-open /mcp, re-run the health tool, and look at the Mac app's window. Do not delete the config first.

Can I install the same MCP server for Claude Code and Cursor?

Yes. Register it in both clients. They do not share config. One running Mac app can serve both if the connector is designed that way.

Is MCP safe on a work Mac?

Treat each server as code you chose to run. Prefer official add flows and signed apps. Do not paste unreadable npx one-liners from social. Project-scoped files should use env vars for secrets.