MCP（模型上下文协议）介绍及opencode配置指南

OpenHarmony Skill Team 2026-04-06 35

MCP（模型上下文协议）介绍及配置指南

在AI技术飞速迭代的今天，大模型“脑强体弱”的困境日益凸显——再强大的模型也难以突破训练数据的时间壁垒，无法无缝连接外部工具与数据源，而MCP（Model Context Protocol，模型上下文协议）的出现，正是为了解决这一痛点。作为Anthropic于2024年底推出的开放标准协议，MCP被誉为“AI世界的USB-C接口”，它通过标准化通信，让AI模型能够即插即用地连接GitHub、文件系统、数据库等各类外部资源，彻底打破协议碎片化、模型绑定性的行业困境，实现“一次适配，服务百模”的跨平台复用效果。本文将重点围绕MCP的核心价值与配置方法展开，尤其详细拆解OpenCode中MCP的具体配置方案，帮助开发者快速上手。

一、MCP核心基础认知

1.1 什么是MCP

MCP是一套用于规范AI模型与外部数据源、工具之间通信的开放协议，核心目标是为AI模型提供通用接口，实现与各类外部系统的无缝交互。简单来说，MCP就像一个“通用插座”，原本需要为每个外部工具定制适配代码的开发模式，如今只需通过MCP协议，就能让所有兼容MCP的AI应用（如OpenCode、Claude Desktop等）快速接入各类工具，大幅降低开发与维护成本。

1.2 MCP的核心架构

MCP采用“宿主-客户端-服务器”三层架构，三者协同工作实现AI与外部资源的通信：

MCP Host（宿主）：承载AI模型的应用，如OpenCode、VS Code、Claude Desktop等，负责理解用户意图并决定调用哪些工具；
MCP Client（客户端）：内置在宿主应用中，通过JSON-RPC协议与MCP Server建立连接，负责传递指令与接收结果；
MCP Server（服务器）：轻量级插件程序，每个服务器对应一种外部资源的能力暴露，例如@modelcontextprotocol/server-github就负责对接GitHub的各类操作接口，支持仓库管理、代码查询等功能。

1.3 MCP的核心价值

相较于传统API集成和Function Calling，MCP具备显著优势：标准化集成降低开发成本，无需为每个工具重复编写适配代码；支持实时双向通信与动态发现，灵活性远超传统方式；统一的安全管控的机制，可避免敏感凭证直接暴露，同时提供细粒度操作审计能力；高复用性可实现“一次开发，多场景使用”，适配各类兼容MCP的AI模型与应用。

二、MCP配置核心前提

在进行MCP配置前，需完成以下基础准备，确保配置过程顺畅：

环境准备：安装Node.js（建议18+版本），确保npm或npx可正常使用（用于调用MCP Server相关依赖包）；
宿主应用准备：本文以OpenCode为例（开源AI编程代理，对MCP支持最完善的终端工具之一），需提前安装OpenCode（可通过npm install -g opencode-ai命令安装）；
敏感凭证准备：若配置GitHub相关MCP服务，需提前获取GitHub个人访问令牌（Personal Access Token），用于身份验证（后续将详细说明获取方法）；
依赖包确认：确保@modelcontextprotocol/server-github包可正常通过npx调用，无需手动全局安装，npx会自动临时下载并执行该包。

三、MCP重点配置流程（以OpenCode为例）

OpenCode作为MCP宿主应用，其MCP配置主要通过项目根目录下的opencode.json文件实现，支持全局配置（~/.config/opencode/opencode.json）和项目级配置（./opencode.json），推荐使用项目级配置，便于团队共享与版本管理。以下将重点拆解用户指定的GitHub相关MCP配置，同时补充其他常用配置场景，确保覆盖核心需求。

3.1 核心配置文件创建

打开终端，进入你的项目根目录（若没有项目，可新建一个空目录）；
新建opencode.json配置文件（大小写敏感，不可修改文件名），该文件将用于存储MCP的所有配置信息；
配置文件基础结构：opencode.json文件需包含$schema字段（用于指定配置文件格式规范）和mcp字段（核心MCP配置区域），基础模板如下：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    // 此处填写MCP具体配置，如GitHub、文件系统等服务配置
  }
}

3.2 重点配置：GitHub MCP服务（示例）

该配置用于让OpenCode通过MCP协议对接GitHub，实现仓库管理、代码查询、提交推送等操作，核心配置参考用户提供的方案，以下逐字段拆解说明、补充实操细节，确保可直接复制使用（替换敏感信息即可）。

3.2.1 完整配置代码（可直接复制）

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "enabled": true,
      "environment": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

3.2.2 逐字段详细说明（关键必看）

mcp：核心配置节点，所有MCP服务（如GitHub、文件系统等）均在此节点下配置，可同时配置多个不同类型的MCP服务，用键名（如github）区分不同服务；
github：MCP服务的唯一标识（可自定义，建议与服务类型一致，便于区分），对应GitHub相关的MCP Server；
type: "local"：指定MCP Server的运行方式，local表示本地运行（通过npx命令启动本地MCP Server插件），也是最常用的配置方式；若需连接远程MCP Server，可将type改为remote，并补充url、headers等配置（如远程GitHub MCP服务的地址和认证信息）；
command：本地启动MCP Server的命令数组，逐元素说明：
"npx"：用于临时下载并执行@modelcontextprotocol/server-github包，无需手动全局安装该依赖；
"-y"：npx的参数，用于自动确认安装依赖（避免手动输入y确认，提升配置便捷性）；
"@modelcontextprotocol/server-github"：GitHub对应的MCP Server包，负责暴露GitHub的各类操作接口（如仓库查询、文件提交等），该包由MCP官方维护，已迁移至github/github-mcp-server仓库继续开发；
enabled: true：是否启用该MCP服务，true表示启用，false表示禁用（禁用后OpenCode将无法通过该服务对接GitHub）；
environment：环境变量配置区域，用于存储敏感信息（避免硬编码泄露），此处仅需配置GITHUB_PERSONAL_ACCESS_TOKEN：
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"：GitHub个人访问令牌，用于OpenCode通过MCP Server对接GitHub时的身份验证，需将"your-token"替换为你自己的GitHub令牌；

3.3 配置验证与生效方法

配置完成后，需重启OpenCode使配置生效，验证步骤如下：

关闭当前终端中运行的OpenCode（若正在运行）；
重新打开终端，进入项目根目录，输入“opencode”命令启动OpenCode；
启动后，在OpenCode的TUI交互界面输入“/mcp”命令，查看已加载的MCP服务；
若显示“✓ github (local)”，且标注对应工具数量，说明GitHub MCP服务配置成功，可正常使用；若显示异常，需检查令牌是否正确、配置字段是否有误（如type拼写错误、command数组格式错误等）。

3.4 补充配置：多MCP服务共存（可选）

OpenCode支持同时配置多个MCP服务（如GitHub+本地文件系统），只需在mcp节点下添加对应配置即可，示例如下（可直接复制补充）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "enabled": true,
      "environment": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    },
    "filesystem": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/your/project/path"
      ],
      "enabled": true
    }
  }
}

其中，filesystem服务用于对接本地文件系统，需将“/your/project/path”替换为你的项目实际路径，配置生效后，OpenCode可通过MCP协议访问本地文件，实现代码读取、修改等操作。

3.5 使用gitcode mcp

如果你是在gitcode，而非github上做开发。你可以下载并安装gitcode_mcp_server。

配置参考如下：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
     "gitcode": {
          "type": "local",
          "command": [
              "python",
              "-m",
              "gitcode_mcp"
          ],
          "enabled": true,
          "environment": {
              "GITCODE_TOKEN": "yout-token"
          }
      }
  }
}

安装配置成功后，opencode中输入/mcps, 显示如下图，表示安装配置成功了。
图片描述

四、MCP配置拓展说明

远程MCP服务配置：若需连接远程GitHub MCP服务（无需本地启动Server），可将type改为remote，补充url和headers配置，示例如下：

"github": {
  "type": "remote",
  "url": "https://api.githubcopilot.com/mcp/",
  "headers": {
    "Authorization": "Bearer your-token"
  },
  "enabled": true
}

配置共享与版本管理：项目级opencode.json文件可提交至Git仓库，实现团队共享，所有团队成员只需替换自己的GitHub令牌，即可使用相同的MCP配置；
其他MCP服务：除了GitHub和文件系统，MCP还支持Brave搜索、PostgreSQL数据库等多种服务，配置方式与GitHub类似，只需替换对应的Server包和环境变量即可（如Brave搜索需配置BRAVE_API_KEY）。

五、总结

MCP作为AI与外部资源交互的标准化协议，彻底解决了传统集成方式的碎片化、高成本问题。

随着MCP生态的不断完善，目前已有400+开源服务器覆盖各类主流平台，未来将支持更多外部工具与数据源，成为AI应用开发的核心基础设施。掌握MCP配置，能大幅提升AI应用的扩展性与实用性，让AI真正突破“时间壁”与“能力壁”，实现更广泛的场景落地。