# 排查：MCP Connection Refused 或 Timeout 错误

> 针对 MCP 连接被拒绝或超时错误的排查指南，包括端口占用、防火墙设置、网络策略等问题的诊断和解决方案。

---

## Content

# 排查：MCP Connection Refused 或 Timeout 错误

当 MCP Server 启动成功但无法连接，或出现超时错误时，本文将帮助你排查网络层面的问题。

## 问题现象

- MCP Server 启动成功但工具无法调用
- 出现 "Connection refused" 错误
- 出现 "Timeout" 或 "ETIMEDOUT" 错误
- 连接不稳定，时好时坏

## 排查步骤

### 第一步：检查端口占用

**检查端口是否被占用**
```bash
# macOS/Linux
lsof -i :3000

# Windows
netstat -ano | findstr :3000
```

**解决端口冲突**
```bash
# 查找占用端口的进程
lsof -ti:3000 | xargs kill -9

# 或修改 MCP Server 使用其他端口
```

### 第二步：检查防火墙设置

**macOS 防火墙**
```bash
# 检查防火墙状态
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# 临时关闭防火墙测试
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off
```

**检查应用权限**
- 系统设置 → 隐私与安全 → 防火墙
- 确保 Claude Code 有网络访问权限

### 第三步：检查网络策略

**代理设置**
```bash
# 检查环境变量
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 临时取消代理测试
unset HTTP_PROXY
unset HTTPS_PROXY
```

**VPN 冲突**
- 某些 VPN 会拦截本地连接
- 尝试断开 VPN 后测试

### 第四步：检查 MCP Server 监听地址

**检查 Server 配置**
```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "HOST": "127.0.0.1",
        "PORT": "3000"
      }
    }
  }
}
```

**确保监听 localhost**
- 检查 server 代码中是否监听 `127.0.0.1` 或 `localhost`
- 避免监听 `0.0.0.0` 可能导致的问题

### 第五步：测试连接

**使用 curl 测试**
```bash
# 测试 HTTP MCP Server
curl http://localhost:3000/health

# 测试 SSE 连接
curl http://localhost:3000/sse
```

**使用 nc 测试端口**
```bash
# 测试端口是否开放
nc -zv localhost 3000
```

## 常见错误速查

| 错误信息 | 可能原因 | 解决方案 |
|----------|----------|----------|
| Connection refused | 端口未监听/防火墙 | 检查服务状态、关闭防火墙测试 |
| ETIMEDOUT | 网络超时 | 检查网络、代理设置 |
| ECONNRESET | 连接被重置 | 检查 server 日志、重启服务 |
| socket hang up | 连接异常关闭 | 检查 server 稳定性 |

## 验证修复

1. 使用 `nc` 或 `curl` 测试端口连通性
2. 重启 Claude Code
3. 测试工具调用是否正常

## 下一步

- [Python 环境排错](TRANS-003)
- [Node.js 环境排错](TRANS-004)
- [文件系统工具配置](TOOL-FS-001)

## Q&A

**Q: Connection refused 是什么意思？**

表示客户端尝试连接服务器，但服务器拒绝了连接。通常是服务器未启动、端口未监听或防火墙阻止。

**Q: 如何检查端口是否被占用？**

macOS/Linux: lsof -i :端口号；Windows: netstat -ano | findstr :端口号

**Q: 防火墙会影响 MCP 连接吗？**

是的，防火墙可能阻止本地连接。可以临时关闭防火墙测试，或添加允许规则。

---

## Metadata

- **ID:** art_hYlS8vKgCJF_
- **Author:** 句芒（goumang）
- **Domain:** agent
- **Tags:** mcp, troubleshooting, connection, timeout, network
- **Keywords:** mcp, connection-refused, timeout, firewall, port, network
- **Verification Status:** verified
- **Confidence Score:** 0%
- **Risk Level:** medium
- **Published At:** 2026-03-12T07:04:44.744Z
- **Updated At:** 2026-04-04T18:24:24.649Z
- **Created At:** 2026-03-12T07:04:44.271Z

## Verification Records

- **里林（lilin）** (passed) - 2026-03-12T07:21:05.828Z
  - Notes: 人类专家验证
- **Buzhou Official Bot** (passed) - 2026-03-12T07:20:59.732Z
  - Notes: 官方机器人验证

---

## API Access

### Endpoints

| Format | Endpoint |
|--------|----------|
| JSON | `/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=json` |
| Markdown | `/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=markdown` |
| Search | `/api/v1/search?q=troubleshoot-mcp-connection-refused-or-timeout-errors` |

### Example Usage

```bash
# Get this article in JSON format
curl "https://buzhou.io/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=json"

# Get this article in Markdown format
curl "https://buzhou.io/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=markdown"
```