Set Up Claude Desktop with MCP Servers in 30 Minutes: A Tutorial

What you’ll need

Claude Desktop with Model Context Protocol (MCP) servers turns the chat app into a personalised agent that can read your filesystem, query your GitHub repos, fetch web pages, and run dozens of other tools, all from inside a regular Claude conversation. This tutorial walks a developer through the full flow in 30 minutes: install the desktop app, edit one config file, add three MCP servers, restart, and test. The flow runs on npx (or uvx for Python servers), with one Docker container for the GitHub server. Most setups need Node.js plus uv for Python servers and Docker for the official GitHub server; the rest pulls in on first run ¹ .

If you are choosing between this and Cursor’s MCP integration, pick Claude Desktop when the team’s primary AI surface is already Claude. Same protocol, simpler config, and the desktop app handles the conversation history. Cursor’s MCP integration matters when the editor itself is the AI surface; the two coexist comfortably.

Three ways to add MCP servers

Claude Desktop supports three onboarding paths for MCP servers as of 2026, and it helps to know all three before picking one ² .

1. One-click via Desktop Extensions (DXT, now MCPB). Settings → Extensions installs .mcpb packages with a single click; secrets are stored in the operating system’s secret vault, and there is no config file to edit. This is the easiest path for vendor-published servers and is the path Anthropic recommends for non-developer users ³ .
2. Custom Connectors at Settings → Connectors. This is the path for remote, cloud-hosted MCP servers that speak HTTP. Useful when the server lives on a SaaS platform rather than running locally.
3. Manual claude_desktop_config.json editing. This tutorial’s path. Pick this when you want full control over environment variables, are running custom servers that have not been packaged as .mcpb files, or want to mix and match local servers across npx, uvx, and Docker. Most builder-side workflows still land here because the config file is the most flexible surface.

The three paths stack rather than replace each other. You can install one server via Extensions, configure another as a Connector, and add a third by editing the JSON file; Claude Desktop reads all three.

Prerequisites

Before you start, make sure the following are in place. The setup itself is short; the prerequisites are where most of the friction is.

• A Claude account. Free tier is fine for trying MCP. Pro (around $20 per month, billed in USD, as of 2026-05-08; verify on Claude’s pricing page before subscribing) lifts the message cap and is what most developers settle on after the first week.
• Node.js 18 or later installed on your machine. npx ships with Node and is what most MCP servers use to run ⁴ . Verify with node --version in a terminal.
• uv installed if you want to use Python-based MCP servers. uvx is the Python equivalent of npx and pulls in Python packages on first run ⁵ . Required for the fetch server later in this tutorial.
• Docker Desktop installed and running. The official GitHub MCP server is a Go binary distributed as a container image (ghcr.io/github/github-mcp-server); Claude Desktop launches it via docker run ⁶ .
• A GitHub personal access token with repo scope. We will create one in Step 4.
• About 30 minutes, including the time to read each step. If you have done any config-file editing before, it will be closer to 15.

The tutorial assumes macOS or Windows on a personal development machine. Anthropic’s quickstart documents Claude Desktop as supported on macOS and Windows only ¹ ; Linux users are covered in a callout near the end. Corporate-managed laptops with restricted network egress may need a proxy configured for npx, uvx, and Docker to reach their respective registries; that is out of scope here.

What this tutorial builds

By the end, your Claude Desktop will have three connected MCP servers:

1. Filesystem. Claude can read, list, and write files inside one or more directories you allow.
2. GitHub (official github/github-mcp-server). Claude can list your repositories, read file contents from any of them, search code, and read issues and pull requests.
3. Fetch. Claude can pull a URL and read the page contents, which is useful for reading documentation pages, RSS feeds, or any public web resource without leaving the chat.

A test query at the end will use all three together: read a local project file, search a related GitHub repo for a function name, and fetch a documentation page. The point of MCP is exactly this: connecting Claude to several data sources so the conversation moves between them naturally, instead of you copy-pasting between tabs.

Step 1: Install Claude Desktop

Download Claude Desktop from claude.ai/download. The page detects your operating system and offers the right installer. macOS gets a .dmg and Windows gets an .exe ⁷ . Linux has no official installer; community builds exist and are covered later in this tutorial.

Install it the usual way for your platform, then sign in with your Claude account. Once signed in, the app should look identical to the web version. The MCP wiring lives one layer below the UI; nothing visible changes until you edit the config file in Step 2.

Image: Claude desktop app download page (claude.ai/download), used for editorial coverage of the installation step in this tutorial.

Step 2: Locate the config file

MCP servers are configured in a single JSON file the desktop app reads at startup. The fastest way to open it is from inside Claude Desktop itself: go to Settings → Developer → Edit Config. Claude Desktop opens the file in your default editor and creates it with an empty scaffold if it does not yet exist ¹ .

If you prefer the terminal, the path depends on the operating system:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

On most systems the file does not exist until you open it through the Settings menu or create it manually. To create it from a terminal:

# macOS
mkdir -p "$HOME/Library/Application Support/Claude"
cat > "$HOME/Library/Application Support/Claude/claude_desktop_config.json" <<'EOF'
{
  "mcpServers": {}
}
EOF

On Windows, open PowerShell and run:

New-Item -ItemType Directory -Force -Path "$env:APPDATA\Claude" | Out-Null
@'
{
  "mcpServers": {}
}
'@ | Set-Content -Path "$env:APPDATA\Claude\claude_desktop_config.json" -Encoding UTF8

Open the file in your editor of choice. Each MCP server you want Claude to talk to becomes one entry inside the mcpServers object. We will add three of them.

Step 3: Add the filesystem MCP server

The filesystem server gives Claude read-and-write access to one or more directories. Edit the config file to look like this, replacing the path with a directory you actually want Claude to see. Your projects directory is a sensible first choice:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ]
    }
  }
}

On Windows, escape the backslashes in the path: "C:\\Users\\yourname\\projects". On macOS, forward slashes are fine.

Two things to know about this server. First, the path you list is the only directory Claude can touch; it cannot escape upward into a parent directory. Second, the -y flag tells npx to install the package automatically on first run without prompting; the first message that uses the filesystem server will take a few seconds longer while npm fetches the package, then it is cached for subsequent runs. The official servers repository at github.com/modelcontextprotocol/servers lists the seven currently active reference servers (Everything, Fetch, Filesystem, Git, Memory, Sequential Thinking, Time) along with installation instructions for each ⁸ .

You can pass multiple directory paths in the args array if you want Claude to see several roots: one for projects, one for documents, and so on. Keep the list small at first; it is easier to widen scope later than to debug why Claude is reading a file you forgot you had granted access to.

Image: github.com/modelcontextprotocol/servers reference servers repository, used for editorial coverage of the official MCP server catalogue this tutorial draws from.

Step 4: Add the official GitHub MCP server

The original @modelcontextprotocol/server-github npm package was archived on 29 May 2025 along with the rest of modelcontextprotocol/servers-archived ⁹ . GitHub’s official replacement is github/github-mcp-server, a Go-based server distributed as a container image at ghcr.io/github/github-mcp-server ⁶ . If you find an older tutorial recommending the archived npm package, skip it; the package is unmaintained and will drift against GitHub API changes.

Create a personal access token first. Go to github.com/settings/tokens and click “Generate new token (classic)”. Give it a clear name like claude-desktop-mcp. Set an expiry; 90 days is a sensible default, and you will rotate it later. Tick the repo scope (full control of private repositories) ¹⁰ . The official github/github-mcp-server uses scope filtering: tools that need additional scopes (issue management, profile reads) silently disable themselves if your token does not carry those scopes, so you can start narrow and widen later ⁶ . Generate the token. Copy it immediately, because GitHub only shows it once.

Make sure Docker Desktop is running, then add the GitHub server to your config:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ]
    },
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

The docker run -i --rm flags keep stdin open (MCP uses stdin and stdout as the transport) and remove the container when it exits. The -e GITHUB_PERSONAL_ACCESS_TOKEN flag tells Docker to forward that environment variable from Claude Desktop’s env block into the container; the token sits in the env block at the top level, which is the standard way MCP servers receive secrets through Claude Desktop. The config file lives on your local machine and is not synced anywhere, but it is still a good idea to keep it out of any directory you have indexed for backup or screen-share. If you use a password manager, store the token there and copy-paste at config time rather than typing it in plain text twice.

If you want fine-grained tokens instead of classic ones, GitHub supports those too. They let you scope access to a specific set of repositories rather than your entire account. The trade is more clicks at creation time and a slightly different scope model. For a single-developer setup, classic tokens with a 90-day expiry are usually fine.

Image: GitHub documentation on personal access tokens (docs.github.com), used for editorial coverage of the token-creation step.

Step 5: Add the fetch MCP server

The fetch server is the simplest of the three. It needs no token and no path. Add it to the config:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ]
    },
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

The fetch server is the one Python entry in this tutorial; it ships through uvx rather than npx. If you skipped the uv installation earlier, this is the moment to come back and install it ⁵ . mcp-server-fetch is the only official fetch implementation and lives in the active modelcontextprotocol/servers repository ⁸ .

The fetch server can read any public URL that responds to a normal GET request. It cannot log in to a site, submit a form, or pretend to be a browser running JavaScript. For docs pages, README files, RSS feeds, and most plain HTML, it works as expected. For single-page-app dashboards that render with client-side JavaScript, it returns the empty shell rather than the rendered content.

Step 6: Restart Claude Desktop and test

Save the config file. Quit Claude Desktop fully. On macOS, that means right-click the menu bar icon and choose Quit, not just close the window. On Windows, exit from the system tray. Then relaunch.

The first launch with new servers will take a few seconds longer while npx, uvx, and Docker fetch the server packages and image. After that, MCP servers show up as a slider icon in the bottom-right corner of the conversation input area ¹ . Click it to confirm all three servers are connected. If any are missing, jump to the pitfalls section below.

Now run a test query that exercises all three:

Read the README.md from my projects/some-repo directory.
Then look up the same repo on my GitHub and tell me which
branch is the default. Finally, fetch
https://modelcontextprotocol.io/quickstart/user and
summarise the three top-level sections.

Claude will use the filesystem server for the first ask, the GitHub server for the second, and the fetch server for the third. If the response covers all three accurately, the setup is working. If one fails (usually the GitHub one, because of token scope or a stopped Docker daemon), the error message will tell you which server returned an error. Fix the scope, regenerate the token if needed, restart Docker if needed, restart Claude Desktop, and try again.

Image: Anthropic Claude Code MCP documentation (code.claude.com/docs/en/mcp), used for editorial coverage of the protocol details and config-file shape.

Common pitfalls

A few specific failures are worth flagging upfront. Each one is fast to fix once you know what to look for.

Path errors on Windows. Backslashes in JSON strings need to be escaped: "C:\\Users\\yourname\\projects", not "C:\Users\yourname\projects". The single-backslash version parses as JSON but looks for a literal path with control characters and fails silently. The MCP server log will show a “no such directory” error when you check.

Docker daemon not running. The GitHub server runs through Docker; if Docker Desktop is not running, the server fails on launch. Start Docker Desktop, wait until it shows “Docker Desktop is running” in the menu bar, then restart Claude Desktop.

GitHub token scope too narrow. A token with only the public_repo scope cannot read private repositories. If your test query returns “I cannot find that repository”, the most likely cause is scope. Regenerate with the broader repo scope and update the config. The official github/github-mcp-server reports which tools were filtered out due to insufficient scope at startup, so the server log is the place to check ⁶ .

Permission prompts on first run. macOS will ask you to grant Claude Desktop permission to access the filesystem path you listed. Approve it. If you decline by accident, go to System Settings → Privacy & Security → Files & Folders and grant the permission manually.

npx cannot reach the npm registry. If you are on a corporate or college network with restricted egress, npx may fail to download the server package. The error log will mention ETIMEDOUT or EAI_AGAIN. Try a personal hotspot first to confirm the issue, then ask your network admin for a proxy config or use a self-hosted npm mirror.

Config file syntax errors. A trailing comma after the last entry in mcpServers is the most common one. JSON does not allow it. If Claude Desktop launches but no MCP icon appears, validate the config file with cat claude_desktop_config.json | python -m json.tool (macOS) or jq . claude_desktop_config.json (any platform with jq installed). The validator will point at the offending line.

Token in source control. Your config file should never end up in a git repository. If you use dotfiles or a similar config-tracker, add the Claude config path to your ignore list. If you have already committed a token, regenerate it on GitHub immediately. The old one is exposed in your git history regardless of subsequent commits.

Linux: unofficial community builds only

Anthropic does not ship a Linux installer for Claude Desktop. The MCP project’s own quickstart documents Claude Desktop as available for macOS and Windows ¹ , and claude.ai/download only offers macOS and Windows binaries ⁷ . Linux users on Debian, Ubuntu, and Arch typically install via aaddrick/claude-desktop-debian, an unofficial community build that extracts and repackages the Windows Electron bundle ¹¹ . The repository ships .deb and AppImage builders along with the steps to produce them locally.

Two consequences are worth knowing if you go this route. First, the unofficial Linux build is not covered by Anthropic support; bug reports go to the community repository, not to Anthropic. Second, the Linux config-file path that the unofficial build reads is ~/.config/Claude/claude_desktop_config.json ¹¹ . The mcpServers block shape is identical to the macOS and Windows versions, so the rest of this tutorial transfers cleanly once Claude Desktop itself is installed.

Where to go next

Once the three core servers are wired up, the natural next steps come from the active reference repository at github.com/modelcontextprotocol/servers. As of writing, the seven active reference servers are Everything (a kitchen-sink test server), Fetch (which we already have), Filesystem (which we already have), Git (local Git repository operations), Memory (a simple key-value memory store for cross-conversation persistence), Sequential Thinking (a structured reasoning helper), and Time (timezone and current-time queries) ⁸ .

Of those, Git, Memory, and Sequential Thinking are the most useful additions for a developer workflow. Git lets Claude run git log, git diff, git blame, and similar read-only commands against a local repository, which pairs well with the filesystem server already in place. Memory persists state between conversations so Claude can remember context you have set up across sessions. Sequential Thinking helps for longer reasoning chains where you want Claude to break a problem into named steps before answering.

Postgres, SQLite, Slack, GitLab, Brave Search, Google Drive, Sentry, and several other servers that older tutorials reference were moved to modelcontextprotocol/servers-archived in May 2025 ⁹ . The archived versions still work but are unmaintained; for production workflows, prefer third-party servers actively maintained by the relevant vendor or community. Notion, for example, has its own community-maintained MCP server outside the official servers repo.

If your workflow needs something the active reference servers do not cover, writing a custom MCP server is straightforward. The protocol uses standard input and output streams as the transport, which means a custom server can be a Node script, a Python script, a Go binary, or anything else that reads JSON-RPC messages from stdin and writes JSON-RPC messages to stdout. The Model Context Protocol specification documents the message shapes, capability negotiation, and transport definitions in full ¹² .

For teams already using Claude Code (the CLI), the same MCP servers work there. Claude Code stores local-scope MCP server configuration in ~/.claude.json (a flat JSON file in your home directory, not inside a ~/.claude/ subdirectory) and user-scope settings in ~/.claude/settings.json ¹³ . The recommended way to add MCP servers to Claude Code is via the claude mcp add CLI command, which writes the entry for you ¹⁴ . A server you set up for Claude Desktop can be migrated by running claude mcp add with the same command and arguments, which keeps the development environment consistent with the chat surface.

That is the 30-minute path. The MCP ecosystem is moving fast, so the official servers repository, the GitHub server’s release notes, and the protocol specification are the three pages worth bookmarking for periodic re-reads.