How to Install MCP Server in Claude Code: Complete Guide

前置条件（2 分钟）

检查你的系统是否已安装：

bash
检查 Node.js（推荐 v18+）
node --version
检查 Python（可选，部分 MCP Server 需要）
python3 --version

如果没有，分别下载：

Node.js：https://nodejs.org

Python：https://python.org

---

方法 1：NPM 安装（最简单，推荐新手）⭐⭐⭐⭐⭐

第 1 步：打开 Claude Code 配置文件

找到 Claude Code 的配置目录：

macOS/Linux：

bash
~/.claude/config.json

Windows：

%APPDATA%\Claude\config.json

如果文件不存在，新建一个。

第 2 步：添加 MCP Server 配置

编辑 config.json，添加以下内容：

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

第 3 步：重启 Claude Code

完全关闭再打开 Claude Code。在底部状态栏应该能看到「MCP Connected」的绿色指示器。

第 4 步：测试是否成功

在 Claude Code 中输入：

Can you list files in my current directory?

Claude 应该能直接回复你的文件列表，说明 MCP Server 已正常工作。

---

方法 2：Docker 安装（适合生产环境）⭐⭐⭐⭐

Docker 的好处是完全隔离，不污染本地环境。

第 1 步：安装 Docker

下载 Docker Desktop：https://www.docker.com/products/docker-desktop

第 2 步：拉取 MCP Server 镜像

bash
以 PostgreSQL MCP Server 为例
docker pull modelcontextprotocol/server-postgres:latest

第 3 步：在 Claude Code 中配置

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

第 4 步：测试连接

在 Claude Code 中输入：

Show me the table schema for 'users' table

---

方法 3：从源码编译（高级用户）⭐⭐⭐⭐⭐

适合需要定制化的情况。

第 1 步：克隆仓库

bash
git clone https://github.com/modelcontextprotocol/servers.git
cd servers/src/filesystem  # 以 filesystem server 为例

第 2 步：安装依赖并构建

bash
npm install
npm run build

第 3 步：在 Claude Code 中指向本地路径

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

---

⚠️ 常见错误与解决方案

错误 1：「MCP Server failed to start」

原因：通常是 npx 找不到包或版本不兼容。

解决：

bash
1. 清除 npm 缓存
npm cache clean --force
2. 更新 npm 到最新版本
npm install -g npm@latest
3. 重新安装 MCP Server
npx @modelcontextprotocol/server-filesystem --version

错误 2：「Port already in use」

原因：MCP Server 默认端口被占用（通常是 3000）。

解决：

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

错误 3：「Permission denied」

原因：MCP Server 文件缺少执行权限（Linux/macOS）。

解决：

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

---

🎯 实战：安装 3 个最常用的 MCP Server

快速安装脚本

bash
#!/bin/bash
一键安装 3 个必装 MCP Server
npm install -g \
  @modelcontextprotocol/server-filesystem \
  @modelcontextprotocol/server-postgres \
  @modelcontextprotocol/server-github
echo "✅ 安装完成！编辑 ~/.claude/config.json，添加以下配置："
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

保存为 install-mcp.sh，运行：

bash
bash install-mcp.sh

---

📊 性能调优

问题：MCP Server 响应很慢

解决：

检查网络连接

bash
   ping modelcontextprotocol.io
   

增加超时时间

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

启用缓存

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

---

✅ 验证清单

安装完成后，逐项检查：

[ ] Claude Code 状态栏显示「MCP Connected」（绿色）

[ ] 能在 Claude 中访问文件系统（filesystem）

[ ] 能查询数据库（如果安装了 postgres）

[ ] 能访问 GitHub（如果安装了 github）

[ ] Claude 响应时间 < 3 秒

---

下一步

学习如何写自定义 MCP Server（见《如何写 SKILL.md 文件》）

按场景选择更多 MCP Server（见《Best MCP Servers 2026》）

加入社区：https://github.com/modelcontextprotocol/community-servers

祝你使用愉快！有问题？ 在 https://aiskillnav.com/mcp 上查看完整 MCP 列表。