The Complete Guide to Installing MCP Servers

Integrating MCP servers into your workflow is easier than it sounds. While the underlying technology is sophisticated, the actual setup process typically takes less than 5 minutes. This comprehensive guide will walk you through every installation method, from the simplest npx approach to containerized Docker deployments.

1. Prerequisites

Before installing most MCP servers, you'll need the following installed on your computer. The specific requirements depend on which installation method you choose:

For JavaScript/TypeScript Servers (Most Common)

• Node.js 18+: Most community servers are written in TypeScript and require Node.js runtime. Download from nodejs.org. We recommend the LTS version for stability.
• npm or yarn: Package managers that come with Node.js. npm is included by default.

For Python Servers

• Python 3.10+: Required for Python-based MCP servers. Download from python.org.
• uv (recommended): A fast Python package manager. Install with pip install uv or via Homebrew on macOS.

For All Methods

• Claude Desktop App: Currently the primary client for MCP. Ensure you have the latest version installed from claude.ai/download.
• Git (Optional): Useful if you want to clone server repositories locally instead of using npx.
• A code editor: VS Code, Cursor, or any text editor for editing configuration files.

node --version    # Should show v18.0.0 or higher
npm --version     # Should show 8.0.0 or higher
python --version  # Should show 3.10 or higher (if using Python servers)

2. Method 1: The Zero-Install Method (npx)

The absolute easiest way to use an MCP server is via npx. This tool, which comes with Node.js, allows you to execute packages without permanently installing them on your system. This is the recommended approach for most users getting started.

Configuration Steps

1. Locate your Claude configuration file. On macOS, you can find it here:

   ~/Library/Application Support/Claude/claude_desktop_config.json

   On Windows, it is typically located at:

   %APPDATA%\Claude\claude_desktop_config.json

   On Linux:

   ~/.config/Claude/claude_desktop_config.json

2. Add the server to the mcpServers object. Here's an example adding the official filesystem server:

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

   The -y flag automatically confirms the package installation prompt.

3. Save the file and restart Claude Desktop completely (quit and reopen, not just close the window).

Popular npx Servers to Try

• @modelcontextprotocol/server-filesystem - Read and write local files
• @modelcontextprotocol/server-github - Interact with GitHub repositories
• @modelcontextprotocol/server-postgres - Query PostgreSQL databases
• @modelcontextprotocol/server-sqlite - Work with SQLite databases
• @modelcontextprotocol/server-brave-search - Web search capabilities

3. Method 2: Persistent Local Installation

If you are developing your own server, need to modify the source code of an existing one, or want faster startup times, you'll want to run servers from a local directory.

When to Use Local Installation

• You're developing or customizing a server
• You need to pin a specific version
• You want faster startup times (no download on each run)
• You're working offline frequently

Installation Steps

1. Clone the repository:

   git clone https://github.com/modelcontextprotocol/servers.git cd servers/src/filesystem

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Update your config to point to the built file:

   {
     "mcpServers": {
       "local-filesystem": {
         "command": "node",
         "args": [
           "/absolute/path/to/servers/src/filesystem/dist/index.js",
           "/Users/yourname/Documents"
         ]
       }
     }
   }

4. Method 3: Docker Containers

For servers that require complex dependencies (like database drivers, specific system libraries, or isolated environments), using Docker ensures a consistent, reproducible setup.

Advantages of Docker

• Isolated environment - won't conflict with your system
• Reproducible across different machines
• Easy to manage complex dependencies
• Better security through containerization

Basic Docker Configuration

{
  "mcpServers": {
    "postgres-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "DATABASE_URL=postgresql://user:pass@host:5432/db",
        "mcp/postgres-server"
      ]
    }
  }
}

Mounting Volumes

If your server needs access to local files, mount them as volumes:

{
  "mcpServers": {
    "filesystem-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/Users/yourname/Documents:/data:ro",
        "mcp/filesystem-server",
        "/data"
      ]
    }
  }
}

The :ro suffix makes the mount read-only for added security.

For a comprehensive guide on Docker deployments, see our dedicated guide on Using Docker for MCP.

5. Method 4: Python Servers with uvx

Many MCP servers are written in Python. The uvx command (from the uv package manager) provides a similar zero-install experience to npx but for Python packages.

Installing uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip
pip install uv

# Or with Homebrew
brew install uv

Using uvx for Python Servers

{
  "mcpServers": {
    "python-server": {
      "command": "uvx",
      "args": [
        "mcp-server-fetch"
      ]
    }
  }
}

6. Environment Variables and Secrets

Many servers require API keys or other secrets. Never hardcode these in your configuration file. Instead, use the env property:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Better: Use Environment Variables

For better security, reference environment variables from your shell:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Then set the variable in your shell profile (~/.zshrc or ~/.bashrc).

7. Running Multiple Servers

You can run as many servers as you need simultaneously. Claude will automatically choose the appropriate tool based on your request:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgresql://..." }
    }
  }
}

8. Troubleshooting Common Issues

Server Doesn't Appear in Claude

• Check JSON syntax: Use a JSON validator. Common issues include trailing commas and missing quotes.
• Restart Claude completely: Quit the app (Cmd+Q on Mac) and reopen it.
• Check the logs: On macOS: tail -f ~/Library/Logs/Claude/mcp*.log

Permission Errors

• Ensure the paths you're granting access to exist
• Check file permissions with ls -la
• On macOS, you may need to grant Full Disk Access to Claude in System Preferences

Server Crashes on Startup

• Verify Node.js version: node --version (need 18+)
• Check if required environment variables are set
• Try running the server manually: npx -y @modelcontextprotocol/server-name

For more detailed troubleshooting, see our Debugging MCP Servers guide.

9. Best Practices

• Start simple: Begin with npx and one server before adding complexity
• Use read-only access: When possible, grant read-only permissions to servers
• Limit scope: Only grant access to directories the server actually needs
• Keep secrets secure: Use environment variables, not hardcoded values
• Update regularly: npx always gets the latest version; for local installs, update periodically
• Monitor logs: Check Claude's MCP logs when debugging issues