Skip to content

MCP (Model Context Protocol) 完全指南

Model Context Protocol (MCP) 是由 Anthropic 开发的开放标准协议,旨在为 AI 应用程序提供安全、标准化的方式来连接外部数据源和工具。简单来说,MCP 就像是 AI 助手的"插件系统",让 AI 能够安全地访问你的文件、数据库、API 等各种资源。

🤔 MCP 是什么?

核心概念

想象一下,你的 AI 助手就像一个非常聪明的助理,但它被困在一个房间里,无法直接访问你的文件、数据库或其他工具。MCP 就是为这个助理提供的"安全通道",让它能够:

  • 📁 读取你的文件 - 分析代码、文档、数据
  • 🗄️ 查询数据库 - 获取业务数据进行分析
  • 🔧 使用工具 - 执行计算、搜索、API 调用
  • 🌐 访问网络资源 - 获取实时信息

为什么需要 MCP?

在 MCP 出现之前,每个 AI 应用都需要自己实现与外部系统的集成,这导致:

重复开发 - 每个应用都要重新造轮子
安全风险 - 缺乏统一的安全标准
兼容性差 - 不同系统间难以互操作
维护困难 - 每个集成都需要单独维护

MCP 解决了这些问题:

标准化接口 - 统一的协议规范
内置安全 - 权限控制和数据保护
即插即用 - 一次开发,到处使用
生态丰富 - 社区贡献的大量工具

🏗️ MCP 架构原理

三层架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI 应用       │    │   MCP 服务器    │    │   外部资源      │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ Claude/GPT  │ │    │ │ 协议处理器  │ │    │ │ 文件系统    │ │
│ │             │ │◄──►│ │             │ │◄──►│ │             │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ MCP 客户端  │ │    │ │ 安全管理器  │ │    │ │ 数据库      │ │
│ │             │ │    │ │             │ │    │ │             │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
└─────────────────┘    └─────────────────┘    └─────────────────┘

工作流程

  1. AI 应用发起请求 - "我需要读取这个文件"
  2. MCP 客户端转换请求 - 将请求转换为标准 MCP 协议
  3. MCP 服务器验证权限 - 检查是否有访问权限
  4. 执行操作 - 安全地访问目标资源
  5. 返回结果 - 将结果返回给 AI 应用

🚀 如何使用 MCP?

1. 快速开始 - Claude Desktop

最简单的方式是通过 Claude Desktop 使用 MCP:

安装 Claude Desktop

bash
# macOS
brew install --cask claude

# 或从官网下载
# https://claude.ai/download

配置 MCP 服务器

编辑 Claude Desktop 配置文件:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key-here"
      }
    }
  }
}

重启 Claude Desktop,你就可以让 Claude 访问指定目录的文件了!

2. 主流编辑器接入 MCP

除了 Claude Desktop,现在越来越多的主流编辑器和 AI 工具开始支持 MCP 协议。以下是各个编辑器的具体接入方法:

2.1 Cursor

Cursor 是基于 VSCode 的 AI 代码编辑器,原生支持 MCP 协议。

安装和配置
  1. 下载 Cursor
bash
# 从官网下载
# https://cursor.sh
  1. 配置 MCP 服务器

打开 Cursor 设置,找到 "MCP Servers" 选项,或者直接编辑配置文件:

macOS: ~/Library/Application Support/Cursor/User/settings.json
Windows: %APPDATA%\Cursor\User\settings.json
Linux: ~/.config/Cursor/User/settings.json

json
{
  "mcp.servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "env": {}
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "/path/to/repo"],
      "env": {}
    }
  }
}
  1. 使用方式

配置完成后,在 Cursor 的 AI 聊天界面中,你可以直接询问:

  • "分析当前项目的代码结构"
  • "查看最近的 Git 提交记录"
  • "帮我重构这个函数"

2.2 Trae AI

Trae AI 是新一代的 AI 开发环境,内置了强大的 MCP 支持。

配置方法
  1. 安装 Trae AI
bash
# 从官网下载
# https://trae.ai
  1. MCP 配置

Trae AI 提供了图形化的 MCP 配置界面:

  • 打开 Trae AI
  • 进入 "Settings" → "MCP Servers"
  • 点击 "Add Server" 添加新的 MCP 服务器

或者编辑配置文件 ~/.trae/mcp-config.json

json
{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"],
      "description": "文件系统访问"
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${env:DATABASE_URL}"
      },
      "description": "数据库查询"
    }
  }
}
  1. 高级功能

Trae AI 支持:

  • 动态服务器发现 - 自动检测项目中可用的 MCP 服务器
  • 权限管理 - 细粒度的访问控制
  • 服务器监控 - 实时查看 MCP 服务器状态

2.3 Visual Studio Code

VSCode 通过扩展支持 MCP 协议。

安装 MCP 扩展
  1. 安装扩展
bash
# 在 VSCode 扩展市场搜索并安装
# "MCP Client" 或 "Model Context Protocol"
  1. 配置扩展

在 VSCode 设置中添加 MCP 配置:

json
{
  "mcp.servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"],
      "cwd": "${workspaceFolder}"
    },
    "python-tools": {
      "command": "python",
      "args": ["-m", "mcp_server_python"],
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  },
  "mcp.autoStart": true,
  "mcp.logLevel": "info"
}
  1. 与 GitHub Copilot 集成
json
{
  "github.copilot.advanced": {
    "mcp.enabled": true,
    "mcp.servers": ["filesystem", "git"]
  }
}

2.4 CherryStudio

CherryStudio 是一个现代化的 AI 聊天客户端,支持多种 AI 模型和 MCP 协议。

配置步骤
  1. 下载 CherryStudio
bash
# 从 GitHub 下载最新版本
# https://github.com/kangfenmao/cherry-studio
  1. MCP 配置

在 CherryStudio 中配置 MCP:

  • 打开 "设置" → "MCP 服务器"
  • 添加新的服务器配置
json
{
  "name": "本地文件系统",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Projects"],
  "env": {},
  "autoStart": true
}
  1. 多模型支持

CherryStudio 支持将 MCP 与不同的 AI 模型结合使用:

  • Claude 3.5 Sonnet + MCP
  • GPT-4 + MCP
  • 本地模型 + MCP

2.5 Zed Editor

Zed 是一个高性能的代码编辑器,通过插件支持 MCP。

配置方法
  1. 安装 MCP 插件
bash
# 在 Zed 中安装 MCP 插件
# Cmd+Shift+P → "Install Extension" → 搜索 "MCP"
  1. 配置文件

编辑 ~/.config/zed/settings.json

json
{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceRoot}"]
      }
    },
    "enabled": true
  }
}

2.6 JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm)

JetBrains 系列 IDE 通过官方插件支持 MCP。

安装和配置
  1. 安装插件
  • 打开 IDE
  • 进入 "Settings" → "Plugins"
  • 搜索并安装 "MCP Support"
  1. 配置 MCP 服务器

在 "Settings" → "Tools" → "MCP" 中配置:

xml
<mcp-servers>
  <server name="filesystem" command="npx" auto-start="true">
    <args>
      <arg>-y</arg>
      <arg>@modelcontextprotocol/server-filesystem</arg>
      <arg>${PROJECT_DIR}</arg>
    </args>
  </server>
  <server name="database" command="python" auto-start="false">
    <args>
      <arg>-m</arg>
      <arg>mcp_server_database</arg>
    </args>
    <env>
      <var name="DB_URL" value="${DB_CONNECTION_STRING}" />
    </env>
  </server>
</mcp-servers>

2.7 Neovim

Neovim 通过 Lua 插件支持 MCP 协议。

配置示例
  1. 安装插件

使用 lazy.nvim 或其他插件管理器:

lua
-- ~/.config/nvim/lua/plugins/mcp.lua
return {
  "mcp-nvim/mcp.nvim",
  config = function()
    require("mcp").setup({
      servers = {
        filesystem = {
          command = "npx",
          args = {"-y", "@modelcontextprotocol/server-filesystem", vim.fn.getcwd()},
          auto_start = true
        },
        git = {
          command = "npx",
          args = {"-y", "@modelcontextprotocol/server-git", vim.fn.getcwd()},
          auto_start = true
        }
      }
    })
  end
}
  1. 使用方式
lua
-- 在 Neovim 中使用 MCP
vim.keymap.set('n', '<leader>mf', ':MCPReadFile<CR>', { desc = 'MCP Read File' })
vim.keymap.set('n', '<leader>mg', ':MCPGitStatus<CR>', { desc = 'MCP Git Status' })

2.8 通用配置技巧

环境变量管理

为了在不同编辑器间共享 MCP 配置,可以使用环境变量:

bash
# ~/.bashrc 或 ~/.zshrc
export MCP_FILESYSTEM_PATH="/Users/yourname/Projects"
export MCP_DATABASE_URL="postgresql://localhost:5432/mydb"
export MCP_API_KEYS_PATH="/Users/yourname/.config/mcp/api-keys.json"
配置模板

创建通用的 MCP 配置模板:

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${MCP_FILESYSTEM_PATH:-/tmp}"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "${MCP_FILESYSTEM_PATH:-/tmp}"]
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${MCP_DATABASE_URL}"
      }
    }
  }
}
故障排除

常见问题和解决方案

  1. 服务器启动失败
bash
# 检查 Node.js 版本
node --version  # 需要 >= 18

# 清理 npm 缓存
npm cache clean --force

# 重新安装 MCP 服务器
npm install -g @modelcontextprotocol/server-filesystem
  1. 权限问题
bash
# 确保目录有正确的权限
chmod 755 /path/to/directory

# 检查文件所有权
ls -la /path/to/directory
  1. 网络连接问题
bash
# 测试网络连接
curl -I https://registry.npmjs.org

# 使用代理(如果需要)
npm config set proxy http://proxy.company.com:8080

3. 编程集成

Python 示例

python
import asyncio
from mcp import ClientSession, StdioServerParameters

class MCPClient:
    def __init__(self):
        self.session = None
    
    async def connect_to_filesystem(self, allowed_path):
        """连接到文件系统 MCP 服务器"""
        server_params = StdioServerParameters(
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem", allowed_path]
        )
        self.session = await ClientSession.create(server_params)
    
    async def read_file(self, file_path):
        """读取文件内容"""
        response = await self.session.read_resource(f"file://{file_path}")
        return response.contents[0].text
    
    async def list_files(self, directory):
        """列出目录中的文件"""
        response = await self.session.call_tool("list_directory", {
            "path": directory
        })
        return response.content[0].text

# 使用示例
async def main():
    client = MCPClient()
    await client.connect_to_filesystem("/Users/yourname/Documents")
    
    # 读取文件
    content = await client.read_file("/Users/yourname/Documents/example.txt")
    print(f"文件内容: {content}")
    
    # 列出文件
    files = await client.list_files("/Users/yourname/Documents")
    print(f"目录内容: {files}")

if __name__ == "__main__":
    asyncio.run(main())

TypeScript 示例

typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

class MCPClient {
  private client: Client;
  private transport: StdioClientTransport;

  async connect(serverCommand: string, args: string[]) {
    this.transport = new StdioClientTransport({
      command: serverCommand,
      args: args
    });
    
    this.client = new Client({
      name: "my-client",
      version: "1.0.0"
    }, {
      capabilities: {}
    });
    
    await this.client.connect(this.transport);
  }

  async readFile(filePath: string): Promise<string> {
    const response = await this.client.request(
      { method: "resources/read", params: { uri: `file://${filePath}` } },
      { method: "resources/read" }
    );
    return response.contents[0].text;
  }
}

// 使用示例
async function main() {
  const client = new MCPClient();
  await client.connect("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]);
  
  const content = await client.readFile("/path/to/file.txt");
  console.log("文件内容:", content);
}

main().catch(console.error);

🛠️ 热门 MCP 服务器推荐

官方服务器

1. 文件系统服务器

bash
npx @modelcontextprotocol/server-filesystem /path/to/directory

功能: 安全地访问本地文件和目录
适用场景: 代码分析、文档处理、数据读取

2. Git 服务器

bash
npx @modelcontextprotocol/server-git /path/to/repo

功能: 访问 Git 仓库信息、提交历史、分支状态
适用场景: 代码审查、项目分析、版本管理

3. 数据库服务器

bash
npx @modelcontextprotocol/server-sqlite /path/to/database.db

功能: 查询 SQLite 数据库
适用场景: 数据分析、报表生成、业务查询

4. 网络搜索服务器

bash
# Brave Search
npx @modelcontextprotocol/server-brave-search

# Google Search
npx @modelcontextprotocol/server-google-maps

功能: 实时网络搜索、地图查询
适用场景: 信息检索、位置服务、实时数据

社区热门服务器

1. Postgres 数据库

bash
npm install @modelcontextprotocol/server-postgres

功能: 连接 PostgreSQL 数据库
配置示例:

json
{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/dbname"
    }
  }
}

2. Slack 集成

bash
npm install @modelcontextprotocol/server-slack

功能: 发送消息、读取频道、管理工作区
适用场景: 团队协作、通知发送、信息同步

3. GitHub 集成

bash
npm install @modelcontextprotocol/server-github

功能: 管理仓库、创建 Issue、审查 PR
适用场景: 代码管理、项目协作、自动化工作流

4. Docker 管理

bash
npm install @modelcontextprotocol/server-docker

功能: 管理容器、镜像、网络
适用场景: 容器编排、环境管理、部署自动化

5. AWS 服务

bash
npm install @modelcontextprotocol/server-aws

功能: 管理 EC2、S3、Lambda 等 AWS 服务
适用场景: 云资源管理、成本优化、自动化运维

📦 从哪里获取 MCP 服务器?

1. 官方仓库

GitHub: https://github.com/modelcontextprotocol
NPM: https://www.npmjs.com/org/modelcontextprotocol

bash
# 查看所有官方服务器
npm search @modelcontextprotocol/server

# 安装特定服务器
npm install -g @modelcontextprotocol/server-filesystem

2. 社区资源

Awesome MCP

GitHub: https://github.com/punkpeye/awesome-mcp
精选的 MCP 服务器、工具和资源列表

MCP Hub

网站: https://mcp-hub.com
社区维护的 MCP 服务器目录

3. 自建服务器

Python 模板

bash
git clone https://github.com/modelcontextprotocol/python-sdk
cd python-sdk/examples

TypeScript 模板

bash
git clone https://github.com/modelcontextprotocol/typescript-sdk
cd typescript-sdk/examples

4. 企业级解决方案

Anthropic 官方支持

第三方服务商

  • MCP Cloud: 托管式 MCP 服务
  • Enterprise MCP: 企业级安全和管理

🔧 实战案例

案例 1: 代码审查助手

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "/path/to/project"]
    }
  }
}

使用方式: "请帮我审查最近的提交,检查代码质量和潜在问题"

案例 2: 数据分析助手

json
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://localhost:5432/analytics"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data/reports"]
    }
  }
}

使用方式: "分析销售数据库中的趋势,并生成可视化报告"

案例 3: DevOps 助手

json
{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-docker"]
    },
    "aws": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-aws"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret",
        "AWS_REGION": "us-west-2"
      }
    }
  }
}

使用方式: "检查生产环境的容器状态,如有问题请自动重启"

🔒 安全最佳实践

1. 权限最小化

json
{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y", 
      "@modelcontextprotocol/server-filesystem", 
      "/home/user/safe-directory"  // 只允许访问特定目录
    ]
  }
}

2. 环境变量管理

bash
# 使用 .env 文件
echo "DATABASE_URL=postgresql://localhost:5432/mydb" > .env
echo "API_KEY=your-secret-key" >> .env

# 在配置中引用
{
  "env": {
    "DATABASE_URL": "${DATABASE_URL}",
    "API_KEY": "${API_KEY}"
  }
}

3. 网络隔离

json
{
  "mcpServers": {
    "internal-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://internal-host:5432/db"
      }
    }
  }
}

🚀 进阶技巧

1. 自定义 MCP 服务器

python
# my_custom_server.py
from mcp.server import Server
from mcp.types import Resource, Tool

app = Server("my-custom-server")

@app.list_resources()
async def list_resources():
    return [
        Resource(
            uri="custom://data/users",
            name="用户数据",
            description="系统用户信息"
        )
    ]

@app.read_resource()
async def read_resource(uri: str):
    if uri == "custom://data/users":
        # 返回用户数据
        return "用户数据内容..."
    
@app.list_tools()
async def list_tools():
    return [
        Tool(
            name="send_email",
            description="发送邮件",
            inputSchema={
                "type": "object",
                "properties": {
                    "to": {"type": "string"},
                    "subject": {"type": "string"},
                    "body": {"type": "string"}
                }
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "send_email":
        # 发送邮件逻辑
        return f"邮件已发送到 {arguments['to']}"

if __name__ == "__main__":
    app.run()

2. 批量操作

python
async def batch_file_analysis(client, file_paths):
    """批量分析多个文件"""
    results = []
    for path in file_paths:
        content = await client.read_resource(f"file://{path}")
        # 分析文件内容
        analysis = analyze_code(content.contents[0].text)
        results.append({
            "file": path,
            "analysis": analysis
        })
    return results

3. 错误处理和重试

python
import asyncio
from typing import Optional

class RobustMCPClient:
    def __init__(self, max_retries: int = 3):
        self.max_retries = max_retries
        self.session: Optional[ClientSession] = None
    
    async def safe_read_resource(self, uri: str) -> Optional[str]:
        """安全读取资源,带重试机制"""
        for attempt in range(self.max_retries):
            try:
                response = await self.session.read_resource(uri)
                return response.contents[0].text
            except Exception as e:
                if attempt == self.max_retries - 1:
                    print(f"读取资源失败: {uri}, 错误: {e}")
                    return None
                await asyncio.sleep(2 ** attempt)  # 指数退避
        return None

🔮 未来发展

即将到来的功能

  1. 多模态支持 - 图像、音频、视频处理
  2. 流式传输 - 大文件和实时数据处理
  3. 分布式架构 - 跨网络的 MCP 服务器集群
  4. AI 代理编排 - 多个 AI 代理协同工作
  5. 企业级管理 - 权限管理、审计日志、合规性

生态系统发展

  • 更多官方服务器 - 覆盖更多主流服务和工具
  • 企业级解决方案 - 安全、可扩展的企业部署
  • 可视化工具 - 图形化配置和管理界面
  • 性能优化 - 更快的响应速度和更低的资源消耗

📚 学习资源

官方文档

社区资源

  • Discord 社区: https://discord.gg/mcp
  • Reddit: r/ModelContextProtocol
  • Stack Overflow: 标签 model-context-protocol

教程和示例

🎯 总结

MCP 正在重新定义 AI 应用与外部世界的交互方式。通过提供标准化、安全的接口,MCP 让 AI 助手能够:

🔹 安全访问 你的文件、数据库和工具
🔹 标准化集成 避免重复开发和维护成本
🔹 生态共享 利用社区贡献的丰富资源
🔹 企业就绪 满足安全性和合规性要求

无论你是开发者、数据分析师还是企业用户,MCP 都能帮你构建更强大、更安全的 AI 应用。现在就开始你的 MCP 之旅吧!


MCP 作为 AI 应用程序的标准化连接协议,正在成为构建智能系统的重要基础设施。通过提供安全、标准化的接口,MCP 使 AI 助手能够安全地访问各种外部资源,同时保持用户的控制权和隐私保护。随着生态系统的不断发展,MCP 将在 AI 应用的普及和标准化方面发挥越来越重要的作用。