MCP (Model Context Protocol) servers are the fastest way to give Claude Code new capabilities — browser automation, database access, GitHub workflows, web search, and thousands more. Installing one takes a single command. Here’s the complete guide, from first install to troubleshooting.
What Is an MCP Server?
An MCP server is a small program that exposes tools to an AI agent over a standard protocol. When you connect one to Claude Code, Claude can call its tools directly: query your Postgres database, drive a headless browser, read your Notion pages, or search the web.
Think of MCP as a USB port for AI — the protocol is the port, and each server is a device you plug in. The ecosystem has exploded: our MCP servers directory tracks the best of 57,000+ MCP repositories on GitHub, organized by category.
The Quick Version
If you just want the command:
# Install a local (stdio) MCP server
claude mcp add my-server -- npx -y @some/mcp-server
# Install a remote (HTTP) MCP server
claude mcp add --transport http my-server https://example.com/mcp
# Verify it's connected
claude mcp list
That’s it. The rest of this guide explains scopes, config files, real examples, and what to do when something breaks.
Step 1: Pick a Server
Start with servers that are official, popular, and actively maintained. Good first installs:
| Server | What it does | Install command |
|---|---|---|
| Playwright MCP | Browser automation — navigate, click, screenshot | claude mcp add playwright -- npx -y @playwright/mcp@latest |
| GitHub MCP | Issues, PRs, repos via the GitHub API | claude mcp add --transport http github https://api.githubcopilot.com/mcp/ |
| Filesystem | Read/write files in allowed directories | claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/projects |
| Postgres | Query databases with natural language | claude mcp add pg -- npx -y @modelcontextprotocol/server-postgres "postgresql://localhost/mydb" |
Browse our curated MCP directory to find servers by category — browser automation, databases, cloud, security, productivity, and more — ranked by GitHub stars.
Step 2: Install with claude mcp add
MCP servers come in two flavors, and the install syntax differs slightly.
Local (stdio) servers
These run as a subprocess on your machine. Everything after -- is the command that starts the server:
claude mcp add <name> -- <command to run the server>
Real example with the official fetch server:
claude mcp add fetch -- npx -y @modelcontextprotocol/server-fetch
If the server needs environment variables (API keys are common), pass them with -e:
claude mcp add brave -e BRAVE_API_KEY=your-key-here -- npx -y @modelcontextprotocol/server-brave-search
Remote (HTTP/SSE) servers
These run on someone else’s infrastructure — no local process needed:
claude mcp add --transport http <name> <url>
Many hosted servers use OAuth. After adding one, run /mcp inside Claude Code to complete authentication in your browser.
Step 3: Choose the Right Scope
This is the part most people miss. Claude Code stores MCP config at three levels:
| Scope | Flag | Stored in | Use when |
|---|---|---|---|
| Local (default) | --scope local |
Your user config, per-project | Personal experiments in one project |
| Project | --scope project |
.mcp.json in the repo root |
The whole team should get this server |
| User | --scope user |
Your user config, all projects | You want it everywhere you work |
Example — share a Playwright server with your whole team by committing .mcp.json:
claude mcp add playwright --scope project -- npx -y @playwright/mcp@latest
This writes a .mcp.json file you can commit:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp@latest"]
}
}
}
Anyone who clones the repo and runs Claude Code gets prompted to approve and use the same server.
Step 4: Verify and Use
# List all configured servers and their status
claude mcp list
# Get details for one server
claude mcp get playwright
Inside a Claude Code session, type /mcp to see connection status, authenticate OAuth servers, and inspect the tools each server provides. Then just ask naturally — “take a screenshot of example.com” — and Claude picks the right tool.
To remove a server:
claude mcp remove playwright
Troubleshooting
Server shows “failed to connect”
Run the server command by hand (e.g., npx -y @playwright/mcp@latest) and read the error. Nine times out of ten it’s a missing dependency, a bad path, or Node being too old.
Tools don’t appear in the session
Restart Claude Code after adding a server. Check /mcp for status. For project-scope servers, make sure you approved the .mcp.json prompt.
Environment variables not picked up
Pass them at install time with -e KEY=value. Servers don’t automatically inherit your shell exports in all setups.
Windows-specific failures with npx
On native Windows (not WSL), wrap the command: claude mcp add my-server -- cmd /c npx -y @some/package.
Too many tools / context bloat
Each connected server adds tool definitions to the model’s context. Keep only the servers you actually use; remove the rest with claude mcp remove.
Security Tips
- Treat MCP servers like any dependency: read the repo before you run it. A malicious server can exfiltrate whatever you give it access to.
- Prefer official servers (from
modelcontextprotocol, Anthropic, or the vendor itself) over random forks. - Scope filesystem servers to specific directories, never
/or~. - Don’t paste production database credentials into a server config you haven’t audited — use a read-only user.
- Our MCP directory lists star counts and authors so you can judge maintenance and adoption at a glance.
Frequently Asked Questions
Do MCP servers cost anything?
The servers themselves are almost all open source and free. Some connect to paid APIs (AWS, Notion, Brave Search) which have their own pricing.
What’s the difference between MCP in Claude Code and Claude Desktop?
Same protocol, different config. Claude Desktop uses claude_desktop_config.json (edit via Settings → Developer). Claude Code uses claude mcp add and .mcp.json. A stdio server that works in one works in the other.
Can I use MCP servers with Cursor or other editors?
Yes. Cursor reads .cursor/mcp.json with the same mcpServers format. Most agent IDEs have adopted the protocol — that’s the point of a standard.
How many MCP servers should I install?
Start with 2–3 you’ll use daily. Every server’s tools consume context window, so a lean setup keeps Claude faster and cheaper.
Where do I find more servers?
Our MCP servers directory is curated and updated regularly — official infrastructure, browser automation, databases, cloud, security, and more, ranked by GitHub stars. For reusable agent workflows, also see the Claude Code skills directory.