MCP 本地调试优先使用 stdio 传输模式，无需配置端口。仅在采用 HTTP SSE 传输模式时，需绑定 localhost 特定端口并在客户端配置对应 URL。

命令速用版

若使用 HTTP SSE 传输模式，启动服务器时指定 host 和 port 参数，确保绑定 127.0.0.1。

# Python SDK 示例
uvicorn my_mcp_server:app `--host` 127.0.0.1 `--port` 8080

# Node.js 示例
npx @modelcontextprotocol/server-example `--port` 8080

若使用 stdio 模式，直接通过命令行管道启动，无需端口参数。

# 客户端配置中直接调用命令
python my_mcp_server.py

为什么会这样

MCP 协议设计了两层传输机制，stdio 用于本地安全通信，HTTP 用于网络通信。

stdio 模式通过标准输入输出直接在进程间传递数据，不涉及网络栈，因此不需要端口映射，安全性更高且延迟更低。HTTP SSE 模式基于网络协议，必须监听特定端口才能接收请求。本地调试时若误用 HTTP 模式却未正确绑定 localhost，会导致客户端无法连接或暴露服务到公网。

分步处理

按以下步骤配置 MCP 本地调试环境，确保传输模式与端口设置匹配。

步骤 1：确认传输模式
查看 MCP Server 文档或代码，确认其支持 stdio 还是 HTTP SSE。大多数本地工具推荐 stdio。

步骤 2：启动服务器
若为 HTTP 模式，启动命令中显式指定 `--host` 127.0.0.1。避免使用 0.0.0.0 以防本地防火墙拦截或意外暴露。

步骤 3：配置客户端
在 MCP Client 配置文件（如 config.json）中填写对应连接信息。stdio 模式填命令路径，HTTP 模式填 http://127.0.0.1:端口/sse。

步骤 4：处理端口冲突
若端口被占用，更换未使用的端口（如 8081, 3000），并同步更新客户端配置 URL。

怎么验证是否生效

通过客户端日志和服务器输出确认连接状态，无需依赖外部工具。

检查点 1：服务器日志
观察服务器启动日志，确认显示 "Listening on 127.0.0.1:端口" 或 "Stdio transport initialized"。

检查点 2：客户端状态
在客户端界面查看 MCP 连接状态，应显示 "Connected" 或 "Ready"，无红色报错。

检查点 3：功能调用
尝试调用一个 MCP Tool 或读取 Resource，若返回真实数据则端口映射与协议协商成功。

常见坑

本地调试中端口绑定地址和防火墙策略是最容易出错的地方。

绑定地址错误
若绑定 0.0.0.0，部分安全软件会拦截本地回环请求。始终优先使用 127.0.0.1。

客户端配置协议头
HTTP 模式下，URL 必须包含 http:// 前缀。缺少协议头会导致客户端无法识别传输类型。

容器环境差异
若在 Docker 中调试，需将容器端口映射到宿主机 localhost，否则客户端无法访问容器内端口。

常见问题

MCP 本地调试必须配置端口吗？

不一定，stdio 模式不需要端口，仅 HTTP 模式需要。

端口被占用如何快速更换？

修改启动命令的 port 参数，并同步更新客户端配置中的 URL 端口号。

客户端连接超时怎么办？

检查服务器是否启动成功，确认防火墙未拦截本地回环流量，验证 URL 地址是否正确。

参考来源

Model Context Protocol Documentation, "Introduction" and "Transport" sections, modelcontextprotocol.io

GitHub - modelcontextprotocol, "specification" repository, github.com/modelcontextprotocol