How to Add MCP Servers to Claude Code

Step-by-step guide to installing and configuring MCP servers in Claude Code. Find servers, edit the config file, and verify tools are loading.

MCP (Model Context Protocol) turns Claude Code from a capable coding assistant into something that can read your filesystem, query your database, search the web, inspect your browser, and call any API — all without leaving your terminal. Adding an MCP server takes about two minutes once you know where the config file lives. This guide walks through the full process from finding servers to verifying they're working in your sessions.

This guide covers the full setup: finding servers, installing them, configuring Claude Code, and verifying everything is working. We'll also cover the most common issues and how to fix them.

What MCP Servers Actually Do

An MCP server is a process that runs alongside Claude Code and exposes tools Claude can call. When you ask Claude to "check the current weather" or "read the contents of my database," Claude is calling a tool exposed by an MCP server running on your machine (or remotely).

The difference from regular Claude: without MCP, Claude can only work with what you paste into the conversation. With MCP, Claude has live, structured access to your systems. It's the difference between asking someone to help you based on a description versus sitting next to them while they look at the actual thing.

There are now over 10,000 MCP servers in the ecosystem — filesystem access, database querying, browser control, code execution, API integrations, and more. Most are open source and free to install.

Where Claude Code Stores MCP Config

Claude Code reads MCP server configuration from a JSON file. The location depends on your platform:

macOS: ~/.claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

If the file doesn't exist yet, create it. Claude Code will pick it up on next start.

The basic structure looks like this:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@package/mcp-server"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

Each entry under mcpServers is one server. The key (e.g., server-name) is what Claude sees when listing available tools — make it descriptive. The command and args define how to start the server process. The env block passes environment variables the server needs (API keys, tokens, etc.).

Finding MCP Servers to Install

Start at the official MCP registry at registry.modelcontextprotocol.io. It lists curated servers with install instructions. For broader search, GitHub has thousands more — search for "mcp-server" plus whatever capability you want (e.g., "mcp-server postgres", "mcp-server github").

A few servers that are widely useful as a starting set:

Filesystem: Read and write files anywhere on your system. Essential for any file-heavy workflow.
Brave Search: Web search from inside Claude. Requires a free Brave API key.
GitHub: Read repos, issues, PRs, and diffs. Useful for code review workflows.
Postgres / SQLite: Direct database query access. Claude can write and run queries against your database.
Puppeteer / Playwright: Browser control. Claude can navigate pages, fill forms, and extract content.

Installing an MCP Server: Step by Step

Most MCP servers are distributed as npm packages or Python packages. Here's the process for each.

npm-based servers (most common)

You don't need to pre-install these — Claude Code will run them via npx, which downloads and executes the package automatically. Just reference them in config:

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

The -y flag auto-confirms the npx download prompt so it doesn't hang waiting for input. The third argument (/Users/yourname) is the root directory the filesystem server is allowed to access — scope this carefully, especially if you're giving Claude write access.

Python-based servers

Python servers need to be installed first:

# Install once
pip install mcp-server-sqlite

# Then reference in config:
{
  "mcpServers": {
    "sqlite": {
      "command": "mcp-server-sqlite",
      "args": ["--db-path", "/path/to/your/database.db"]
    }
  }
}

Local servers (custom or cloned)

If you've cloned a server repository or built your own, point to the entry point directly:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server/index.js"]
    }
  }
}

A Complete Config Example

Here's a real config file with multiple servers set up:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

After saving this file, restart Claude Code completely (quit and reopen, not just a new conversation). New sessions pick up the updated config; active sessions don't hot-reload.

Verifying Servers Are Loaded

Once Claude Code is running with your config, you can verify the servers loaded by asking Claude directly:

What MCP tools do you have available?

Claude will list all loaded tools with their names and descriptions. If a server failed to start, it won't appear in this list.

You can also check from the command line. Claude Code logs MCP server startup in its output. If a server crashes on start (bad config, missing dependency, wrong path), the error will appear there.

Common Setup Issues

"Command not found" on npx

Claude Code might not inherit your full shell PATH, especially on macOS with the desktop app. If npx isn't found, use the full path:

"command": "/usr/local/bin/npx"
// or wherever `which npx` points

Server not appearing in tools list

Check for JSON syntax errors in your config file — a missing comma or bracket will cause the entire file to fail silently. Run your config through a JSON validator (python3 -m json.tool ~/.claude/claude_desktop_config.json) to catch parse errors before debugging further.

Server crashes immediately on start

Usually a missing dependency, wrong path, or missing environment variable. Run the server command directly in your terminal to see the raw error output:

npx -y @modelcontextprotocol/server-filesystem /tmp

If it starts successfully in terminal but not in Claude Code, the issue is usually PATH or environment variable differences between your shell and Claude Code's execution context.

API key errors

Double-check that keys are in the env block, not the args array. Never put secrets in args — those are visible in process listings. The env block passes them as environment variables, which is the right pattern.

Security Considerations

Every MCP server you install is code that runs on your machine with the permissions of your user account. A few practices to keep in mind:

Scope filesystem access. Instead of giving the filesystem server your entire home directory, give it only the directories relevant to your work.
Review server source before installing. For servers with access to sensitive systems (databases, production APIs), read the source or use only well-maintained packages from reputable publishers.
Use read-only tokens where possible. For GitHub, Postgres, and similar integrations, create tokens with only the permissions Claude actually needs.
Don't install servers from untrusted sources. The MCP ecosystem is growing fast; not everything in the wild has been reviewed. Stick to the official registry and well-starred GitHub repositories.

For a full MCP security audit checklist, see our MCP security guide.

Our MCP Servers

We've published several MCP servers available on the official registry and PyPI:

lo-eyes: Visual frontend inspector. Analyzes pages for accessibility issues, color contrast, touch target sizing, and layout problems. Available via pip install lo-eyes.
MCP Shield: Security scanner for MCP server code. Detects common vulnerabilities before you deploy. Available via npm install @sophiacave/mcp-shield.
Apple Foundation Models MCP: Use Apple's on-device AI models (iPhone/Mac) via MCP. Available via pip install apple-fm-mcp.

Claude Desktop App vs Claude Code CLI

MCP works with both the Claude desktop app and the Claude Code CLI, but there's an important distinction. The desktop app and Claude Code share the same claude_desktop_config.json file — so servers you configure there are available in both environments. The key difference is context.

In the Claude desktop app, you're having a conversation that uses MCP tools when needed. You might ask Claude to "look at my project folder" and it reads files via the filesystem server. The interaction is conversational.

In Claude Code (the terminal), MCP servers are deeply integrated into the coding workflow. Claude actively uses them to read files it's editing, check test output, query databases for schema context, and run searches mid-task. The server calls happen frequently and automatically as part of multi-step tasks, not just when you explicitly ask.

For most development workflows, configure MCP servers once and both environments benefit. If you only want a server available in Claude Code but not the desktop app (or vice versa), that level of separation currently requires maintaining separate config files and pointing each environment to a different path — not a built-in feature, but achievable.

Advanced Config Patterns

Disabling a server without removing it

Add a disabled key to temporarily turn off a server:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
      "disabled": true
    }
  }
}

This is useful when a server is causing startup errors you want to troubleshoot later without losing the config.

Multiple instances of the same server

You can run the same server package multiple times with different arguments — useful for multiple databases or filesystem roots:

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

Claude will see these as two distinct tool sets with the names you give them. Choose descriptive names — Claude uses them to select which tool to call.

Pinning versions

The -y flag on npx installs the latest version each time. For stability in production or shared team setups, pin to a specific version:

"args": ["-y", "@modelcontextprotocol/[email protected]", "/path"]

This prevents a server update from breaking your workflow unexpectedly. Check release notes before upgrading pinned servers.

What to Build Once You're Set Up

Once you have a few MCP servers running, the workflow shifts. Instead of copying file contents into chat, you ask Claude to read the file. Instead of pasting database schemas, you ask Claude to query the database. The conversation stays in natural language; the MCP layer handles the system access.

Common patterns that become easy with MCP:

Code review with direct repository access — Claude reads the PR diff, the changed files, and the test output simultaneously
Database-assisted debugging — Claude queries production data to understand what's actually happening instead of hypothesizing
Documentation generation from live code — Claude reads your codebase structure directly and generates accurate docs
Multi-system research — web search + filesystem + database all in one conversation

For the full picture of what MCP makes possible across the growing ecosystem, see our MCP ecosystem guide. For building your own MCP server to expose custom internal tools to Claude, see our build guide. And for the best pre-built servers to start with across every major category, see our curated list. If your team needs help setting up Claude with MCP in a production environment, we consult.