Client guide

Install MCP Servers in Claude Code with Pharos

Claude Code reads MCP servers from its own config, and user-scope installs live in ~/.claude.json. Editing that file by hand means matching its JSON shape exactly. Pharos does the edit for you: one command downloads the server, verifies it, and writes the entry.

This guide covers installing pharos, adding your first server to Claude Code, and what to check when the server does not show up.

Install the Pharos CLI

Pharos ships as a single Go binary. Pick the install path for your system:

# macOS / Linux / WSL
curl -fsSL https://getpharos.dev/install | sh

# Windows PowerShell (not cmd.exe)
irm https://getpharos.dev/install.ps1 | iex

# Go developers
go install github.com/Wpnx330/pharos-cli@latest

Verify

# Check the CLI is on your PATH
pharos version

Install a server into Claude Code

The package name is the ID from search results. Install it with the --client flag pointed at Claude Code:

pharos install echo-mcp-server-for-testing --client claude-code

To add the same server to more clients in one pass, list them comma-separated. The interactive picker does the same job with a menu:

Multiple clients

pharos install echo-mcp-server-for-testing --client claude-code,cursor

Interactive picker

pharos install echo-mcp-server-for-testing --select-clients

Transport decides what install does. stdio servers are downloaded as tarballs and verified before any config entry is written. Remote servers, the kind that run over HTTP, get a URL-based config entry instead, so there is nothing to download.

Where the config lands

User scope: ~/.claude.json

User-scope installs write ~/.claude.json. If you run Claude Code on Windows through WSL2, pharos handles the Windows path variant as well. Entries you added by hand stay as they are.

Every install writes an install receipt: a machine-readable record that shows exactly which config files changed. When you want to know what pharos touched, read the receipt.

Verify the install

Start a new Claude Code session, or restart it, so the config reloads. Then ask what MCP tools it has; the new server should be in the list.

The receipt from the install names the file that changed, so you can confirm the write landed where you expected.

Troubleshooting

The server is not listed in Claude Code

Restart the client so it reloads its config, or start a new session. If it is still missing, re-run the install and check the receipt for the file path pharos wrote.

Installed into the wrong client

Pharos only writes the config files for the --client ids you pass. Install again with the right id, or use --select-clients and pick from the interactive list of clients pharos can configure.

Removing a server

pharos remove echo-mcp-server-for-testing takes the server back out. Use the same package ID you installed with.

Coming from mcpm or manual configs?

Run pharos import. It reads the client config files you already have and adopts the servers in them into pharos.lock. From then on, pharos tracks every change through install receipts, and you can install and update without editing client JSON by hand.

pharos import

Frequently asked questions

Which config file does pharos change for Claude Code?

~/.claude.json for user-scope installs. On WSL2 setups there is a Windows path variant, which pharos handles as well. The install receipt names the exact file that changed.

Can I install one server into several clients at once?

Yes. Pass a comma-separated list, as in pharos install <name> --client cursor,claude-desktop, or run pharos install <name> --select-clients and pick clients from an interactive list.

Will pharos overwrite the MCP servers I already configured?

No. Pharos writes the entry for the server you are installing and preserves the rest of the file. To bring existing configs under pharos management, run pharos import. Every install then records a receipt that shows exactly which files changed.

Get the Pharos CLI

Everything on this page runs on the pharos CLI. Install it with:

# macOS / Linux / WSL
curl -fsSL https://getpharos.dev/install | sh

The full command reference, including every flag pharos install accepts, is on the CLI page.