5 分钟上手 MCP：安装你的第一个 MCP Server

ccAiHub
5 阅读5分钟

5 分钟上手 MCP：安装你的第一个 MCP Server

合集：MCP（模型上下文协议）系列 · 初级篇（二）

前言

上一篇我们理解了 MCP 的概念。这一篇，我们来动手操作——在 Claude Desktop 和 Claude Code 中安装 MCP Server，让 AI 真正能访问你的文件系统和 GitHub。

整个过程只需要 5 分钟。国内使用Claude Code 访问ccAiHub.com

一、准备工作

安装 Claude Desktop 或 Claude Code

方案 A：Claude Desktop（图形界面，推荐新手）

下载地址：claude.ai/download

支持 macOS 和 Windows。

方案 B：Claude Code（命令行，推荐开发者）

npm install -g @anthropic-ai/claude-code
claude

确认 Node.js 已安装

大多数 MCP Server 需要 Node.js 18+：

node --version
# v20.x.x ← 符合要求

二、方案 A：Claude Desktop 安装 MCP Server

2.1 找到配置文件

配置文件位置：

系统路径
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
# macOS：快速打开
open ~/Library/Application\ Support/Claude/

# Windows：在文件资源管理器地址栏输入
%APPDATA%\Claude\

2.2 安装文件系统 MCP Server

文件系统 Server 是官方参考实现，允许 Claude 读取和操作你指定的目录。

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的用户名/Documents",
        "/Users/你的用户名/Projects"
      ]
    }
  }
}

说明：

  • command: 启动 MCP Server 的命令
  • args: 命令参数，这里指定 Claude 可以访问的目录白名单
  • -y: npx 的静默安装标志，自动安装依赖

Windows 路径写法：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\你的用户名\\Documents",
        "C:\\Users\\你的用户名\\Projects"
      ]
    }
  }
}

2.3 安装 GitHub MCP Server

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的用户名/Projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_你的token"
      }
    }
  }
}

GitHub Token 获取：

  1. 打开 github.com/settings/to…
  2. 点击 "Generate new token (classic)"
  3. 选择权限：repo（完整仓库访问）、read:org
  4. 复制生成的 token

2.4 重启 Claude Desktop

配置文件修改后，必须完全退出并重启 Claude Desktop。

验证是否成功：打开 Claude Desktop，在对话框输入：

你现在可以访问我的文件系统吗？列出我的 Projects 目录下有哪些子目录。

如果 Claude 正确列出了你的目录，说明 MCP Server 工作正常。

三、方案 B：Claude Code 安装 MCP Server

Claude Code 支持通过命令行或配置文件管理 MCP Server。

3.1 使用命令行添加

# 添加文件系统 MCP Server
claude mcp add filesystem \
  --command "npx" \
  --args "-y,@modelcontextprotocol/server-filesystem,/your/projects/path"

# 添加 GitHub MCP Server
claude mcp add github \
  --command "npx" \
  --args "-y,@modelcontextprotocol/server-github" \
  --env "GITHUB_PERSONAL_ACCESS_TOKEN=ghp_你的token"

3.2 通过 settings.json 配置

项目级配置（.claude/settings.json）：

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

注意：${GITHUB_TOKEN} 会从系统环境变量中读取，避免把 token 硬编码进配置文件。

全局配置（~/.claude/settings.json）：效果相同，跨所有项目生效。

四、测试：MCP 实战对话

4.1 文件系统测试

你：列出当前目录下所有 TypeScript 文件
Claude：（调用 filesystem MCP）我找到了以下 TypeScript 文件...

你：读取 src/main.ts 的内容，告诉我这个文件做了什么
Claude：（读取文件）这个文件...

你：在 docs/ 目录下创建一个 README.md，描述这个项目的架构
Claude：（创建文件）已创建 docs/README.md，内容如下...

4.2 GitHub 测试

你：查看我的 my-project 仓库最近 5 个 PR，有没有还没 merge 的？
Claude：（调用 github MCP）你的 my-project 仓库有以下开放的 PR...

你：帮我在这个仓库创建一个 Issue，标题是"优化首页加载性能"，描述这几个要优化的点...
Claude：（调用 github MCP 创建 Issue）Issue #42 已创建，链接是...

五、常用 MCP Server 一览

5.1 官方参考实现

Server安装命令功能
文件系统@modelcontextprotocol/server-filesystem读写本地文件
GitHub@modelcontextprotocol/server-github仓库、PR、Issue 管理
Google Drive@modelcontextprotocol/server-gdrive云端文档访问
PostgreSQL@modelcontextprotocol/server-postgres数据库查询
SQLite@modelcontextprotocol/server-sqlite本地 SQLite 操作
网页抓取@modelcontextprotocol/server-fetch获取网页内容
搜索@modelcontextprotocol/server-brave-searchBrave 搜索引擎
Puppeteer@modelcontextprotocol/server-puppeteer浏览器自动化

5.2 社区热门 Server

Server功能
@modelcontextprotocol/server-memory跨会话持久记忆
mcp-server-dockerDocker 容器管理
mcp-server-linearLinear 项目管理
mcp-server-notionNotion 知识库
mcp-server-slackSlack 消息操作
mcp-server-awsAWS 服务管理

完整列表：github.com/punkpeye/aw…

六、排查常见问题

问题 1：Claude 说"我没有访问文件系统的能力"

原因：MCP Server 未成功启动。

排查步骤：

# 手动运行 MCP Server，看是否有报错
npx -y @modelcontextprotocol/server-filesystem /your/path

# 检查配置文件 JSON 格式是否合法
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

问题 2：GitHub 操作提示权限不足

原因：GitHub Token 权限不够或已过期。

解决：重新生成 Token，确保勾选了正确的权限范围（repo、read:org）。

问题 3：Windows 路径中文乱码

原因：JSON 文件编码问题。

解决：确保 claude_desktop_config.json 保存为 UTF-8 编码（无 BOM）。

问题 4：npx 命令找不到

原因：Node.js 未安装或未加入 PATH。

解决：

# 检查
which npx || where npx

# 重新安装 Node.js
# https://nodejs.org

七、安全注意事项

7.1 文件系统访问权限最小化

只授权 Claude 确实需要访问的目录，不要开放整个磁盘：

// ❌ 危险：开放根目录
"args": ["@modelcontextprotocol/server-filesystem", "/"]

// ✅ 安全：只开放项目目录
"args": ["@modelcontextprotocol/server-filesystem", "/Users/me/Projects/my-app"]

7.2 Token 不要提交到 Git

// ❌ 硬编码 token（危险，可能提交到 Git）
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_abc123" }

// ✅ 从环境变量读取
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }

八、本篇小结

5 分钟你完成了：

  • ✅ 安装文件系统 MCP Server
  • ✅ 安装 GitHub MCP Server
  • ✅ 验证 MCP 正常工作
  • ✅ 了解常用 MCP Server 生态

下一篇，我们将覆盖 MCP 生态的全貌：数据库连接、搜索引擎、开发者工具，以及如何选择合适的 MCP Server 组合。

系列导航

  • 初级篇（一）：MCP 是什么？AI 世界的 USB-C 接口详解
  • 初级篇（二）：5 分钟上手：安装你的第一个 MCP Server ← 当前
  • 初级篇（三）：MCP 生态地图：工具、数据库、搜索全覆盖
  • 中级篇（一）：动手构建 MCP Server：Python & TypeScript 实战
  • 中级篇（二）：深入三大原语：Resources、Tools 和 Prompts
  • 中级篇（三）：MCP + RAG：构建企业知识库问答系统
  • 高级篇（一）：企业级 MCP 架构：安全、认证与高可用
  • 高级篇（二）：MCP OAuth 2.1 实战：标准化身份认证
  • 高级篇（三）：MCP + 多智能体编排：下一代 AI 工作流
avatar
文章
阅读
粉丝