MCP集成完整指南：从配置到开发的实战手册

MCP集成完整指南：从配置到开发的实战手册 MCP集成完整指南：从配置到开发的实战手册 Modified June 10 Code block Plain Text npx @modelcontextprotocol/inspector node ./dist/index.js ⠀ 然后访问 http://127.0.0.1:6274 ⠀ Q15：如何发布MCP到npm？ ⠀ A： Code block Plain Text npm login npm run build npm publish access public ⠀ 安全问题 ⠀ Q16：API Key泄露了怎么办？ ⠀ A： 1. 立即删除泄露的Key 2. 创建新Key 3. 更新环境变量 4. 检查使用记录是否异常 ⠀ Q17：如何安全管理API Key？ ⠀ A： • ✅ 使用环境变量，不硬编码 • ✅ 使用 ${VAR} 语法引用 • ✅ .mcp.json 只放引用，不放值 • ✅ 敏感配置放Local作用域 • ❌ 不要提交包含Key的文件到Git ⠀ Q18：MCP服务器能访问我的所有文件吗？ ⠀ A：不能。Filesystem MCP只能访问你在配置中指定的目录。 ⠀ 其他问题 ⠀ Q19：MCP支持哪些AI工具？ ⠀ A：已支持： • Claude Desktop • Claude Code • VS Code + Continue • Cursor • Zed • 以及更多支持MCP协议的工具 ⠀ Q20：哪里找更多MCP服务器？ ⠀ A： • 官方仓库：https://github.com/modelcontextprotocol/servers • Awesome列表：https://github.com/punkpeye/awesome mcp servers • MCP Server Finder：https://www.mcpserverfinder.com/ 总结与检查清单 ⠀ 学习成果检查 ⠀ 完成本课后，你应该能够： ⠀ 理解MCP价值：能向他人解释MCP是什么、为什么重要配置基础MCP：成功配置Filesystem MCP并调用工具配置GitHub MCP：正确设置Token并管理仓库配置数据库MCP：连接SQLite或PostgreSQL 理解三作用域：知道Local/Project/User的区别和使用场景排查常见问题：能独立解决配置和连接错误开发简单MCP：能创建包含Tool的MCP服务器（可选） ⠀ 配置检查清单 ⠀ 在项目中使用MCP前，确认： ⠀ .mcp.json 文件存在且格式正确所需环境变量已配置 API Key安全存储（不在配置文件中硬编码） Claude Code启动时显示MCP服务器已连接至少测试过一个MCP工具调用 ⠀ 推荐下一步 ⠀ 1. 配置更多服务器：根据你的开发需求，配置Context7、Brave Search等 2. 深入学习：阅读MCP官方文档了解更多高级特性 3. 开发自定义MCP：将你的常用工具封装成MCP服务器 4. 参与社区：在GitHub上分享你开发的MCP服务器附录 ⠀ 附录A：完整.mcp.json模板 ⠀ Code block Plain Text { "mcpServers": { "filesystem": { "command": "npx", "args": [" y", "@modelcontextprotocol/server filesystem", "./src", "./docs"], "env": {} }, "github": { "command": "npx", "args": [" y", "@modelcontextprotocol/server github"], "env": { "GITHUB PERSONAL ACCESS TOKEN": "${GITHUB PERSONAL ACCESS TOKEN}" } }, "sqlite": { "command": "uvx", "args": ["mcp server sqlite", " db path", "./data/app.db"], "env": {} }, "context7": { "command": "npx", "args": [" y", "@upstash/context7 mcp"], "env": {} }, "brave search": { "command": "npx", "args": [" y", "@modelcontextprotocol/server brave search"], "env": { "BRAVE API KEY": "${BRAVE API KEY}" } }, "memory": { "command": "npx", "args": [" y", "@modelcontextprotocol/server memory"], "env": {} }, "fetch": { "command": "uvx", "args": ["mcp server fetch"], "env": {} }, "sequential thinking": { "command": "npx", "args": [" y", "@modelcontextprotocol/server sequential thinking"], "env": {} }, "puppeteer": { "command": "npx", "args": [" y", "@modelcontextprotocol/server puppeteer"], "env": {} } } } ⠀ 附录B：MCP命令速查表 ⠀ 命令功能示例重要 claude mcp list 列出所有MCP服务器 claude mcp list ⭐ claude mcp add 添加MCP服务器 claude mcp add fs npx y @.../server filesystem ./ ⭐ claude mcp get 查看服务器详情 claude mcp get github claude mcp remove 删除服务器 claude mcp remove github claude mcp debug 调试模式启动 claude mcp debug ⭐ ⠀ ⚠️ 重要澄清：claude mcp test 和 claude mcp restart 命令不存在。如需测试服务器，使用 claude mcp get <name 查看状态；如需重启，退出并重新启动Claude Code。 ⠀ 附录C：官方MCP服务器列表 ⠀ 服务器包名功能重要 Filesystem @modelcontextprotocol/server filesystem 文件系统操作 ⭐ GitHub @modelcontextprotocol/server github GitHub仓库管理 ⭐ GitLab @modelcontextprotocol/server gitlab GitLab仓库管理 Git mcp server git（Python/uvx）本地Git操作 SQLite mcp server sqlite（Python/uvx） SQLite数据库 ⭐ PostgreSQL @modelcontextprotocol/server postgres PostgreSQL数据库 Memory @modelcontextprotocol/server memory 持久化记忆 Fetch mcp server fetch（Python/uvx）网页获取 Time mcp server time（Python/uvx）时间服务 Sequential Thinking @modelcontextprotocol/server sequential thinking 顺序思考 ⠀ 然后访问 http://127.0.0.1:6274 ⠀ Q15：如何发布MCP到npm？ ⠀ A： ⠀ 安全问题 ⠀ Q16：API Key泄露了怎么办？ ⠀ A： 1. 立即删除泄露的Key 2. 创建新Key 3. 更新环境变量 4. 检查使用记录是否异常 ⠀ Q17：如何安全管理API Key？ ⠀ A： • ✅ 使用环境变量，不硬编码 • ✅ 使用 ${VAR} 语法引用 • ✅ .mcp.json 只放引用，不放值 • ✅ 敏感配置放Local作用域 • ❌ 不要提交包含Key的文件到Git ⠀ Q18：MCP服务器能访问我的所有文件吗？ ⠀ A：不能。Filesystem MCP只能访问你在配置中指定的目录。 ⠀ 其他问题 ⠀ Q19：MCP支持哪些AI工具？ ⠀ A：已支持： • Claude Desktop • Claude Code • VS Code + Continue • Cursor • Zed • 以及更多支持MCP协议的工具 ⠀ Q20：哪里找更多MCP服务器？ ⠀ A： • 官方仓库：https://github.com/modelcontextprotocol/servers • Awesome列表：https://github.com/punkpeye/awesome mcp servers • MCP Server Finder：https://www.mcpserverfinder.com/ 总结与检查清单 ⠀ 学习成果检查 ⠀ 完成本课后，你应该能够： ⠀ 理解MCP价值：能向他人解释MCP是什么、为什么重要配置基础MCP：成功配置Filesystem MCP并调用工具配置GitHub MCP：正确设置Token并管理仓库配置数据库MCP：连接SQLite或PostgreSQL 理解三作用域：知道Local/Project/User的区别和使用场景排查常见问题：能独立解决配置和连接错误开发简单MCP：能创建包含Tool的MCP服务器（可选） ⠀ 配置检查清单 ⠀ 在项目中使用MCP前，确认： ⠀ .mcp.json 文件存在且格式正确所需环境变量已配置 API Key安全存储（不在配置文件中硬编码） Claude Code启动时显示MCP服务器已连接至少测试过一个MCP工具调用 ⠀ 推荐下一步 ⠀ 1. 配置更多服务器：根据你的开发需求，配置Context7、Brave Search等 2. 深入学习：阅读MCP官方文档了解更多高级特性 3. 开发自定义MCP：将你的常用工具封装成MCP服务器 4. 参与社区：在GitHub上分享你开发的MCP服务器附录 ⠀ 附录A：完整.mcp.json模板 ⠀ ⠀ 附录B：MCP命令速查表 ⠀ 命令功能示例重要 claude mcp list 列出所有MCP服务器 claude mcp list ⭐ claude mcp add 添加MCP服务器 claude mcp add fs npx y @.../server filesystem ./ ⭐ claude mcp get 查看服务器详情 claude mcp get github claude mcp remove 删除服务器 claude mcp remove github claude mcp debug 调试模式启动 claude mcp debug ⭐ 命令命令功能功能示例示例重要重要 claude mcp list claude mcp list 列出所有MCP服务器列出所有MCP服务器 claude mcp list claude mcp list ⭐ ⭐ claude mcp add claude mcp add 添加MCP服务器添加MCP服务器 claude mcp add fs npx y @.../server filesystem ./ claude mcp add fs npx y @.../server filesystem ./ ⭐ ⭐ claude mcp get claude mcp get 查看服务器详情查看服务器详情 claude mcp get github claude mcp get github claude mcp remove claude mcp remove 删除服务器删除服务器 claude mcp remove github claude mcp remove github claude mcp debug claude mcp debug 调试模式启动调试模式启动 claude mcp debug claude mcp debug ⭐ ⭐ ⠀ ⚠️ 重要澄清：claude mcp test 和 claude mcp restart 命令不存在。如需测试服务器，使用 claude mcp get <name 查看状态；如需重启，退出并重新启动Claude Code。 ⚠️ 重要澄清：claude mcp test 和 claude mcp restart 命令不存在。如需测试服务器，使用 claude mcp get <name 查看状态；如需重启，退出并重新启动Claude Code。 ⠀ 附录C：官方MCP服务器列表 ⠀ 服务器包名功能重要 Filesystem @modelcontextprotocol/server filesystem 文件系统操作 ⭐ GitHub @modelcontextprotocol/server github GitHub仓库管理 ⭐ GitLab @modelcontextprotocol/server gitlab GitLab仓库管理 Git mcp server git（Python/uvx）本地Git操作 SQLite mcp server sqlite（Python/uvx） SQLite数据库 ⭐ PostgreSQL @modelcontextprotocol/server postgres PostgreSQL数据库 Memory @modelcontextprotocol/server memory 持久化记忆 Fetch mcp server fetch（Python/uvx）网页获取 Time mcp server time（Python/uvx）时间服务 Sequential Thinking @modelcontextprotocol/server sequential thinking 顺序思考服务器服务器包名包名功能功能重要重要 Filesystem Filesystem @modelcontextprotocol/server filesystem @modelcontextprotocol/server filesystem 文件系统操作文件系统操作 ⭐ ⭐ GitHub GitHub @modelcontextprotocol/server github @modelcontextprotocol/server github GitHub仓库管理 GitHub仓库管理 ⭐ ⭐ GitLab GitLab @modelcontextprotocol/server gitlab @modelcontextprotocol/server gitlab GitLab仓库管理 GitLab仓库管理 Git Git mcp server git（Python/uvx） mcp server git（Python/uvx）本地Git操作本地Git操作 SQLite SQLite mcp server sqlite（Python/uvx） mcp server sqlite（Python/uvx） SQLite数据库 SQLite数据库 ⭐ ⭐ PostgreSQL PostgreSQL @modelcontextprotocol/server postgres @modelcontextprotocol/server postgres PostgreSQL数据库 PostgreSQL数据库 Memory Memory @modelcontextprotocol/server memory @modelcontextprotocol/server memory 持久化记忆持久化记忆 Fetch Fetch mcp server fetch（Python/uvx） mcp server fetch（Python/uvx）网页获取网页获取 Time Time mcp server time（Python/uvx） mcp server time（Python/uvx）时间服务时间服务 Sequential Thinking Sequential Thinking @modelcontextprotocol/server sequential thinking @modelcontextprotocol/server sequential thinking 顺序思考顺序思考 Puppeteer @modelcontextprotocol/server puppeteer 浏览器自动化 Brave Search @modelcontextprotocol/server brave search 网页搜索 ⭐ Context7 @upstash/context7 mcp 技术文档 ⭐ ⠀ 附录D：资源链接 ⠀ 官方资源： • MCP官方文档：https://modelcontextprotocol.io/ • MCP规范：https://modelcontextprotocol.io/specification/2025 11 25 • Claude Code MCP文档：https://code.claude.com/docs/en/mcp • 官方服务器仓库：https://github.com/modelcontextprotocol/servers • TypeScript SDK：https://github.com/modelcontextprotocol/typescript sdk • Python SDK：https://github.com/modelcontextprotocol/python sdk ⠀ 社区资源： • Awesome MCP Servers：https://github.com/punkpeye/awesome mcp servers • MCP Server Finder：https://www.mcpserverfinder.com/ • MCP中文站：https://mcpcn.com/ 📌 信息来源： • MCP官方文档 | 验证日期：2026 05 30 • GitHub MCP Server仓库 | 验证日期：2026 05 30 • Claude Code文档 | 验证日期：2026 05 30 MCP官方文档 GitHub MCP Server仓库 Claude Code文档 📌 信息来源： • MCP官方文档 | 验证日期：2026 05 30 MCP官方文档 • GitHub MCP Server仓库 | 验证日期：2026 05 30 GitHub MCP Server仓库 • Claude Code文档 | 验证日期：2026 05 30 Claude Code文档 ⠀ 作者：老金更新日期：2026年5月30日版本：V1.5（v2.1.158 release 摘录入差量）字数统计：约3,500行 / 28,000字适用版本：MCP规范 2025 11 25 / Claude Code v2.1.158 课程信息 ⠀ • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 预计学时：4 6小时 • 难度等级：⭐⭐ 入门级（有Claude Code基础即可） • 更新日期：2026年5月30日 • 适用版本：MCP规范 2025 11 25 / Claude Code v2.1.158（验证于 2026 05 30） • 前置要求：已完成Claude Code安装和基础使用本课学习目标 ⠀ 完成本课学习后，你将能够： ⠀ 1. 理解MCP的核心价值：掌握MCP协议与传统AI工具集成方式的本质区别 2. 配置常用MCP服务器：独立完成Filesystem、GitHub、数据库等10+核心服务器配置 3. 掌握三作用域配置体系：理解Local/Project/User作用域的优先级和适用场景 4. 排查MCP连接问题：独立解决90%的常见配置和连接故障 5. 理解MCP工作原理：掌握STDIO/HTTP传输层和JSON RPC通信机制 6. 开发自定义MCP服务器：从零创建一个可用的MCP服务器（TypeScript） 7. 安全使用MCP：正确管理API密钥和敏感配置学习路径导航（先看这里！） ⠀ 根据你的情况选择学习路径：这是一篇3000+行的长教程，不用全看！根据你的目标选择路径。根据你的情况选择学习路径：这是一篇3000+行的长教程，不用全看！根据你的目标选择路径。 ⠀ 路径A：快速上手（60分钟） ⠀ 适合人群：急着用MCP，想快速配一个看效果 ⠀ 只看这些章节（其他跳过）： ⠀ ⠀ 60分钟后你能达到：成功配置2 3个MCP服务器，Claude Code能调用外部工具路径B：完整学习（4 6小时） ⠀ 适合人群：想深入理解MCP，掌握配置和开发 ⠀ 学习顺序：从头到尾所有章节 ⠀ 建议分段学习： • 第1天（2小时）：第1 3部分（理解+配置） • 第2天（2小时）：第4 5部分（原理+开发） • 第3天（1小时）：第6 7部分（故障排查+FAQ）路径C：问题排查（10分钟） ⠀ 适合人群：MCP配置出问题，需要快速解决 ⠀ 直接跳到这些章节： ⠀ ⠀ 使用方法： 1. 按 Ctrl + F 搜索你的错误信息关键词 2. 找到对应的Q&A 3. 按步骤解决路径D：专项学习（30 60分钟/主题） ⠀ 适合人群：已经会配置MCP，想学习特定功能 ⠀ 想学什么看哪几节预计时间自定义MCP开发第五部分 1.5小时三作用域配置第三部分3.4节 30分钟 MCP工作原理第四部分 45分钟安全最佳实践第三部分3.5节 20分钟想学什么想学什么看哪几节看哪几节预计时间预计时间自定义MCP开发自定义MCP开发第五部分第五部分 1.5小时 1.5小时三作用域配置三作用域配置第三部分3.4节第三部分3.4节 30分钟 30分钟 MCP工作原理 MCP工作原理第四部分第四部分 45分钟 45分钟安全最佳实践安全最佳实践第三部分3.5节第三部分3.5节 20分钟 20分钟术语表（小白必读） ⠀ 在开始之前，先了解这些关键术语。用生活类比帮助理解： ⠀ 术语英文全称通俗解释生活类比 JSON JavaScript Object Notation 一种通用的数据格式，用花括号{}组织数据，MCP配置文件就是JSON格式标准化的表格模板（波浪号） Home Directory 用户的"家目录"，macOS是/Users/用户名，Linux是/home/用户名，Windows对应C:\Users\用户名你电脑上"我的文档"的上级目录 MCP Model Context Protocol AI工具的"USB接口标准"，让AI能连接各种外部工具 USB接口标准 MCP Server • 符合MCP标准的"工具包"，提供特定功能 USB设备（U盘、键盘） MCP Client • 连接和使用MCP Server的程序电脑的USB接口 MCP Host • 运行MCP Client的宿主程序（如Claude Code）电脑主机 Tools • MCP Server提供的"工具函数"，AI可以调用工具箱里的锤子、螺丝刀 Resources • MCP Server提供的"数据资源"，AI可以读取参考书、资料库 Prompts • MCP Server提供的"预设模板"，标准化交互填空表格、问卷模板 STDIO Standard Input/Output "直连线"传输方式，本地进程通信 USB直连线 HTTP Hypertext Transfer Protocol "网线"传输方式，支持远程通信网线/WiFi JSON RPC JSON Remote Procedure Call MCP的通信协议，用JSON格式传递消息对讲机的通话格式作用域 Scope 配置的生效范围（Local/Project/User）房间/楼层/整栋楼 npx Node Package eXecute 临时运行npm包的工具租借工具（用完还）环境变量 Environment Variable 系统级配置，存储敏感信息保险柜里的密码本术语术语英文全称英文全称通俗解释通俗解释生活类比生活类比 JSON JSON JavaScript Object Notation JavaScript Object Notation 一种通用的数据格式，用花括号{}组织数据，MCP配置文件就是JSON格式一种通用的数据格式，用花括号{}组织数据，MCP配置文件就是JSON格式标准化的表格模板标准化的表格模板（波浪号）（波浪号） Home Directory Home Directory 用户的"家目录"，macOS是/Users/用户名，Linux是/home/用户名，Windows对应C:\Users\用户名用户的"家目录"，macOS是/Users/用户名，Linux是/home/用户名，Windows对应C:\Users\用户名你电脑上"我的文档"的上级目录你电脑上"我的文档"的上级目录 MCP MCP Model Context Protocol Model Context Protocol AI工具的"USB接口标准"，让AI能连接各种外部工具 AI工具的"USB接口标准"，让AI能连接各种外部工具 USB接口标准 USB接口标准 MCP Server MCP Server • • 符合MCP标准的"工具包"，提供特定功能符合MCP标准的"工具包"，提供特定功能 USB设备（U盘、键盘） USB设备（U盘、键盘） MCP Client MCP Client • • 连接和使用MCP Server的程序连接和使用MCP Server的程序电脑的USB接口电脑的USB接口 MCP Host MCP Host • • 运行MCP Client的宿主程序（如Claude Code）运行MCP Client的宿主程序（如Claude Code）电脑主机电脑主机 Tools Tools • • MCP Server提供的"工具函数"，AI可以调用 MCP Server提供的"工具函数"，AI可以调用工具箱里的锤子、螺丝刀工具箱里的锤子、螺丝刀 Resources Resources • • MCP Server提供的"数据资源"，AI可以读取 MCP Server提供的"数据资源"，AI可以读取参考书、资料库参考书、资料库 Prompts Prompts • • MCP Server提供的"预设模板"，标准化交互 MCP Server提供的"预设模板"，标准化交互填空表格、问卷模板填空表格、问卷模板 STDIO STDIO Standard Input/Output Standard Input/Output "直连线"传输方式，本地进程通信 "直连线"传输方式，本地进程通信 USB直连线 USB直连线 HTTP HTTP Hypertext Transfer Protocol Hypertext Transfer Protocol "网线"传输方式，支持远程通信 "网线"传输方式，支持远程通信网线/WiFi 网线/WiFi JSON RPC JSON RPC JSON Remote Procedure Call JSON Remote Procedure Call MCP的通信协议，用JSON格式传递消息 MCP的通信协议，用JSON格式传递

在小宇宙note 阅读完整内容