Claude Code MCP Setup: Connect Your First Server

What You Will Have After This Guide

By the end of this guide, you will have three MCP servers connected to Claude Code: Filesystem (read/write your local files), GitHub (manage repositories and pull requests), and Playwright (control a real browser). These three together cover the overwhelming majority of real development workflows.

Each connection takes under two minutes. The whole setup takes under ten minutes from a cold start.

Prerequisites

• Claude Code CLI installed (claude --version should work)
• Node.js 18 or higher (node --version)
• A GitHub account with a personal access token (for the GitHub server)
• A project directory to work from

How MCP Connections Work

Each MCP server is a separate process that Claude Code starts and communicates with via the MCP protocol. When you run claude mcp add, you're registering a command that Claude Code will run to start that server. The server process stays running for the duration of your Claude session.

Servers are stored in your Claude Code configuration and persist across sessions — you only need to add them once. Use claude mcp list to see all registered servers, and claude mcp remove <name> to remove one.

Step 1: Connect the Filesystem Server

The Filesystem server is the most important one. It lets Claude read and write files in a directory you specify. Without it, Claude can only work with text you paste directly into the conversation.

# Connect filesystem with your project directory as the allowed path
# Replace /path/to/your/project with an actual path
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/your/project

# Or use . to allow access to the current directory
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .

Scope the path to your project directory, not your entire home folder. This limits what Claude can access and reduces the risk of accidental file modifications. See the Filesystem MCP Server guide for advanced options.

Step 2: Connect the GitHub Server

The GitHub server requires a personal access token. Create one at github.com/settings/tokens with scopes: repo, read:user, and read:org if you work with organizations.

# Set your GitHub personal access token
export GITHUB_TOKEN=ghp_yourTokenHere

# Add the GitHub MCP server
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# On Windows PowerShell, set the env var like this:
# $env:GITHUB_TOKEN = "ghp_yourTokenHere"

To make the token persistent across terminal sessions, add the export to your ~/.bashrc or ~/.zshrc. See the GitHub MCP Server guide for full token scope documentation.

Step 3: Connect Playwright

The Playwright server lets Claude control a real browser. It's the most powerful server for web-related tasks: testing, scraping, form automation, and screenshot capture.

claude mcp add playwright -- npx -y @playwright/mcp

# On first run, Playwright will download browser binaries
# This may take 1-2 minutes

Verify All Connections

# List all registered MCP servers
claude mcp list

# Expected output:
filesystem  npx -y @modelcontextprotocol/server-filesystem /your/path
github      npx -y @modelcontextprotocol/server-github
playwright  npx -y @playwright/mcp

After listing, start claude and ask: "What MCP tools do you have available?" Claude should list tools from all three servers, including read_file, create_pull_request, and navigate.

The .claude/mcp.json Configuration File

MCP server registrations are stored in a JSON configuration file at ~/.claude/mcp.json (global) or .claude/mcp.json in your project directory (project-local). You can edit this file directly to add or modify server configurations.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

Committing the project-local .claude/mcp.json to your repository means teammates get the same server configuration when they clone the repo — they just need to add their own credentials.

Troubleshooting Common Issues

Permission error on Filesystem server: The path you specified doesn't exist or Claude doesn't have read permission. Verify the path with ls /path/to/your/project before running the mcp add command.

GitHub server authentication failure: Your token is missing, expired, or lacks the required scopes. Run echo $GITHUB_TOKEN to confirm it's set. Generate a new token with repo scope at github.com/settings/tokens.

Playwright browser not found: Browser binaries weren't downloaded. Run npx playwright install separately to force the download. This downloads Chromium, Firefox, and WebKit.

Server starts but Claude can't see any tools: Restart Claude Code after adding servers. Some configurations require a fresh session to take effect. Run claude again from the terminal.

Next Steps

With three servers connected, you have a solid foundation. From here you can add database servers (SQLite or PostgreSQL), explore the full MCP server directory, or read about the difference between Skills and MCP servers to understand when each approach works best.