How to Install MCP Server in Claude Code: Complete Guide

Prerequisites (2 minutes)

Check if your system has the following installed:

bash
Check Node.js (recommended v18+)
node --version
Check Python (optional, some MCP Servers require it)
python3 --version

If not, download them:

Node.js: https://nodejs.org

Python: https://python.org

---

Method 1: NPM Installation (Simplest, Recommended for Beginners) ⭐⭐⭐⭐⭐

Step 1: Open Claude Code Configuration File

Locate the Claude Code configuration directory:

macOS/Linux:

bash
~/.claude/config.json

Windows:

%APPDATA%\Claude\config.json

If the file doesn't exist, create a new one.

Step 2: Add MCP Server Configuration

Edit config.json and add the following:

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

Step 3: Restart Claude Code

Fully close and reopen Claude Code. You should see a green "MCP Connected" indicator in the bottom status bar.

Step 4: Test if It Works

In Claude Code, type:

Can you list files in my current directory?

Claude should directly reply with your file list, indicating the MCP Server is working correctly.

---

Method 2: Docker Installation (Suitable for Production) ⭐⭐⭐⭐

The advantage of Docker is complete isolation without polluting the local environment.

Step 1: Install Docker

Download Docker Desktop: https://www.docker.com/products/docker-desktop

Step 2: Pull the MCP Server Image

bash
Example with PostgreSQL MCP Server
docker pull modelcontextprotocol/server-postgres:latest

Step 3: Configure in Claude Code

json
{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-e", "DB_URL=postgresql://user:password@localhost:5432/mydb",
        "modelcontextprotocol/server-postgres:latest"
      ]
    }
  }
}

Step 4: Test the Connection

In Claude Code, type:

Show me the table schema for 'users' table

---

Method 3: Build from Source (Advanced Users) ⭐⭐⭐⭐⭐

Suitable for customization needs.

Step 1: Clone the Repository

bash
git clone https://github.com/modelcontextprotocol/servers.git
cd servers/src/filesystem  # Example with filesystem server

Step 2: Install Dependencies and Build

bash
npm install
npm run build

Step 3: Point to Local Path in Claude Code

json
{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["/path/to/servers/src/filesystem/dist/index.js"]
    }
  }
}

---

⚠️ Common Errors and Solutions

Error 1: "MCP Server failed to start"

Cause: Usually npx cannot find the package or there is a version incompatibility.

Solution:

bash
1. Clear npm cache
npm cache clean --force
2. Update npm to the latest version
npm install -g npm@latest
3. Reinstall the MCP Server
npx @modelcontextprotocol/server-filesystem --version

Error 2: "Port already in use"

Cause: The default port for MCP Server is occupied (usually 3000).

Solution:

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {
        "PORT": "3001"
      }
    }
  }
}

Error 3: "Permission denied"

Cause: MCP Server files lack execute permissions (Linux/macOS).

Solution:

bash
chmod +x ~/.claude/servers/mcp-server-*

---

🎯 Hands-On: Install 3 Most Commonly Used MCP Servers

Quick Installation Script

bash
#!/bin/bash
One-click install 3 must-have MCP Servers
npm install -g \
  @modelcontextprotocol/server-filesystem \
  @modelcontextprotocol/server-postgres \
  @modelcontextprotocol/server-github
echo "✅ Installation complete! Edit ~/.claude/config.json and add the following configuration:"
cat << 'EOF'
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"]
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/db"]
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github", "github_token_here"]
    }
  }
}
EOF

Save as install-mcp.sh and run:

bash
bash install-mcp.sh

---

📊 Performance Tuning

Issue: MCP Server Response is Slow

Solution:

Check Network Connection

bash
   ping modelcontextprotocol.io
   

Increase Timeout

json
   {
     "mcpServers": {
       "postgres": {
         "command": "npx",
         "args": ["@modelcontextprotocol/server-postgres"],
         "timeout": 30000  // 30 seconds
       }
     }
   }
   

Enable Caching

json
   {
     "mcpServers": {
       "filesystem": {
         "command": "npx",
         "args": ["@modelcontextprotocol/server-filesystem"],
         "env": {
           "CACHE_ENABLED": "true",
           "CACHE_TTL": "3600"  // 1 hour
         }
       }
     }
   }
   

---

✅ Verification Checklist

After installation, check each item:

[ ] Claude Code status bar shows "MCP Connected" (green)

[ ] Can access the file system in Claude (filesystem)

[ ] Can query the database (if postgres is installed)

[ ] Can access GitHub (if github is installed)

[ ] Claude response time < 3 seconds

---

Next Steps

Learn how to write a custom MCP Server (see "How to Write a SKILL.md File")

Choose more MCP Servers by scenario (see "Best MCP Servers 2026")

Join the community: https://github.com/modelcontextprotocol/community-servers

Enjoy! Have questions? Check the full MCP list at https://aiskillnav.com/mcp