使用说明

Claude MCP服务器配置

此目录包含Claude的模型上下文协议（MCP）服务器的配置和管理脚本。

概述

MCP服务器通过提供对外部工具和资源的访问来增强Claude的能力。此设置包括：

GitHub MCP服务器：与GitHub存储库集成
Context7 MCP服务器：语义记忆能力
浏览器工具MCP服务器：Web交互工具
木偶MCP服务器：自动浏览器控制
存储库MCP服务器：持久内存存储
知识图谱MCP服务器：结构化知识表示

全球MCP服务器集成

配置路径

每个平台都有特定的MCP配置位置：

克劳德代码:
- Linux/macOS： ~/.config/claude-code/mcp.json
- 窗户： %APPDATA%/Claude Code/mcp.json
克劳德桌面:
- Linux/macOS： ~/.config/claude/claude_desktop_config.json
- 窗户： %APPDATA%/Claude/claude_desktop_config.json
Cline.bot:
- 所有平台： ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

标准配置格式

所有平台都使用一个通用的JSON结构：

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/Desktop", "${HOME}/Downloads"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "browser-tools": {
      "command": "npx",
      "args": ["@agentdeskai/browser-tools-mcp@latest"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  },
  "security": {
    "allowAllMCPToolPermissions": false,
    "requireToolApproval": true,
    "fileSystemAccess": {
      "allowedPaths": ["${HOME}/Desktop", "${HOME}/Downloads", "${HOME}/Documents"],
      "disallowedPaths": ["${HOME}/.ssh", "${HOME}/.config", "${HOME}/.aws"]
    }
  }
}

全球安装

安装所需依赖项:

# Install Node.js dependencies
npm install -g @modelcontextprotocol/server-filesystem @modelcontextprotocol/server-memory @agentdeskai/browser-tools-mcp@latest @upstash/context7-mcp@latest puppeteer-mcp-server @modelcontextprotocol/server-sequential-thinking

# Pull Docker images
docker pull ghcr.io/github/github-mcp-server

配置环境变量: 创建一个 .env 主目录中的文件：

# GitHub integration
export GITHUB_PERSONAL_ACCESS_TOKEN="your_token_here"

# Other platform-specific tokens
export CONFLUENCE_API_TOKEN="your_token_here"
export JIRA_API_TOKEN="your_token_here"

运行配置脚本:

# Configure all platforms
bash scripts/configure-claude-code.sh
bash scripts/configure-claude-desktop.sh
bash scripts/configure-vscode-cline.sh

安全最佳实践

文件权限:

# Set restrictive permissions on config files
chmod 600 ~/.config/claude-code/mcp.json
chmod 600 ~/.config/claude/claude_desktop_config.json
chmod 600 ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

环境变量:
- 将敏感令牌存储在环境变量中
- 为不同平台使用单独的令牌
- 定期轮换代币
- 从不将令牌提交到版本控制
访问控制:
- 配置allowedPaths以限制文件系统访问
- 为敏感操作启用requireToolApproval
- 默认情况下，使用allowAllMCPToolPermissions=false
- 定期审核服务器权限

健康检查

跨平台验证MCP服务器状态：

# Check Claude Code servers
claude mcp list

# Check Claude Desktop
bash scripts/health-check.sh

# Check Cline.bot
code --list-extensions | grep claude

故障排除

服务器连接问题:

# Check if servers are running
ps aux | grep mcp
docker ps | grep mcp

权限错误:

# Fix config file permissions
chmod 600 ~/.config/claude*/mcp*.json

缺少的依赖:

# Reinstall Node.js packages
npm install -g @modelcontextprotocol/server-filesystem @modelcontextprotocol/server-memory

# Rebuild Docker images
docker pull ghcr.io/github/github-mcp-server

日志分析:

# View server logs
cat ~/.config/claude/logs/mcp-servers.log

跨平台兼容性

路径格式:
- 使用${HOME}作为用户主目录
- 即使在Windows上也要使用正斜杠（/）
- 将环境变量用于系统路径
服务器命令:
- 将npx用于Node.js服务器
- 对容器化服务器使用docker run--rm
- 设置适当的环境变量
配置同步:
- 使用scripts/sync-env-to-config.sh同步设置
- 保持一致的安全设置
- 保持服务器版本一致

全局MCP配置

MCP服务器可以跨不同平台进行全局配置，以确保功能一致：

克劳德代码全局配置

位置: ~/.config/claude-code/mcp.json （Linux/macOS）或 %APPDATA%/Claude Code/mcp.json （Windows）
配置:
```
bash scripts/configure-claude-code.sh
```
这将为所有Claude Code工作区在全球范围内设置MCP服务器。

Claude桌面配置

位置:
- Linux/macOS： ~/.config/claude/claude_desktop_config.json
- 窗户： %APPDATA%/Claude/claude_desktop_config.json
配置:
```
bash scripts/configure-claude-desktop.sh
```
这启用了Claude Desktop应用程序中的MCP功能。

Cline.bot全局配置

位置: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
配置:
```
bash scripts/configure-vscode-cline.sh
```
这将使用Cline为所有VS Code工作区设置全局MCP设置。

常见配置选项

所有平台都支持这些核心MCP服务器：

GitHub集成:

{
  "github": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
    }
  }
}

文件系统访问:

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "path1", "path2"]
  }
}

内存管理:

{
  "memory": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-memory"]
  }
}

安全考虑

全局配置MCP时：

文件权限:
- 配置文件应具有600个权限（仅限用户读/写）
- 环境文件也应采取类似的保护措施
许可证管理:
- 将令牌存储在环境变量中
- 如果需要，为不同的平台使用单独的令牌
- 定期轮换代币
访问控制:
- 限制文件系统对必要目录的访问
- 配置外部API访问的允许列表
- 在需要时启用工具批准要求

目录结构

[PROJECT_ROOT]/
├── README.md                # Main documentation
├── product-docs/            # Product & project management documents
├── config/                  # Configuration files
│   └── config.sh            # Environment variables
├── data/                    # Persistent data storage
│   ├── memory-bank/         # Memory Bank MCP data
│   └── knowledge-graph/     # Knowledge Graph MCP data
├── logs/                    # Log files
├── scripts/                 # Utility scripts
│   ├── health-check.sh      # Server health check
│   ├── security-audit.sh    # Security audit script
│   ├── maintenance.sh       # Maintenance tasks
│   └── cleanup.sh           # Cleanup script
└── vscode-integration/      # VS Code integration files
    └── start-servers.sh     # VS Code startup script

快速开始

设置环境变量: 复制 .env.template 向 .env 并使用您的凭据进行编辑。这 GITHUB_PERSONAL_ACCESS_TOKEN 是必需的。

cp .env.template .env
nano .env

运行安装脚本: 这将检查需求、设置权限并准备环境。

bash setup.sh

构建内存库Docker镜像:

bash scripts/build-memory-bank.sh

启动MCP服务器: 此命令将向Claude注册所有MCP服务器。它被设计为在后台运行，例如，作为VS Code任务。

bash vscode-integration/start-servers.sh

测试

该项目包括一个全面的测试套件，以确保脚本的可靠性和正确性。该套件包括单元、集成和端到端测试。

要运行所有测试，请从项目根目录执行以下命令：

bash tests/run_tests.sh

VS代码集成

自动设置

创建一个 .vscode/tasks.json 项目目录中的文件：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start MCP Servers",
      "type": "shell",
      "command": "bash ${workspaceFolder}/vscode-integration/start-servers.sh",
      "isBackground": true,
      "problemMatcher": [],
      "presentation": {
        "reveal": "never",
        "panel": "dedicated",
        "showReuseMessage": false
      },
      "runOptions": {
        "runOn": "folderOpen"
      }
    }
  ]
}

当VS Code打开时，这将自动启动MCP服务器。

运作原理

VS代码集成：

使用锁文件机制来防止重复的服务器实例
确保在VS代码关闭时进行适当的清理
在VS代码重启过程中维护服务器注册
记录所有活动以进行故障排除

可用的MCP服务器

GitHub MCP服务器

目的：与GitHub存储库交互
状态: ✅ 工作中 -使用正确的stdio参数修复
配置：使用Docker容器连接器脚本
需求：Docker、GitHub个人访问令牌
连接方式:
- 使用现有的Docker容器 ghcr.io/github/github-mcp-server
- 连接器脚本： scripts/github-mcp-connector.sh
- 容器ID:自动检测到正在运行的容器

Context7 MCP服务器

目的：语义记忆能力

命令:

claude mcp add "context7-mcp-server" "npx" "@upstash/context7-mcp@latest"

需求：Node.js、npm

浏览器工具MCP服务器

目的：Web交互工具

命令:

claude mcp add "browser-tools-mcp-server" "npx" "@agentdeskai/browser-tools-mcp@latest"

需求：Node.js、npm

木偶MCP服务器

目的：自动浏览器控制

命令:

claude mcp add "puppeteer-mcp-server" "npx" "puppeteer-mcp-server"

需求：Node.js、npm

存储库MCP服务器

目的：持久内存存储
状态: ✅ 工作中 -已修复以防止多个容器
配置：使用带有--rm标志的Docker连接器脚本
需求：Docker，内存库mcp：本地Docker镜像
连接方式:
- 用途 docker run -i --rm 用于清洁的一次性容器
- 连接器脚本： scripts/memory-bank-connector.sh
- 构建图像： bash scripts/build-memory-bank.sh

知识图谱MCP服务器

状态：当前不可用（在npm注册表中找不到包）
目的：结构化知识表示
备注：在工作包可用之前，此服务器将被禁用

安全考虑

此设置包括几个安全功能：

环境变量保护:
- 存储在受保护配置文件中的敏感数据
- 建议权限： chmod 600 config/config.sh
锁定文件机制:
- 防止重复的服务器实例
- 确保终止时进行适当的清理
安全审计脚本:
- 检查暴露的秘密
- 验证文件权限是否正确
- 验证令牌
- 查看自动审批设置

使用以下命令运行安全审核：

bash scripts/security-audit.sh

维护

维护脚本处理：

更新Docker镜像
更新Node.js包
清理Docker资源
备份MCP配置
日志轮转

使用以下方式运行维护：

bash scripts/maintenance.sh

故障排除

常见问题的快速修复

GitHub MCP服务器连接失败

症状: ✘ failed Claude Code中github mcp服务器的状态

解决方案:

检查Docker容器是否正在运行：
```
docker ps | grep github-mcp-server
```

更新连接器脚本中的容器ID：

# Find container ID
CONTAINER_ID=$(docker ps --filter ancestor=ghcr.io/github/github-mcp-server --format "{{.ID}}")
# Update script
sed -i '' "s/CONTAINER_ID=\".*\"/CONTAINER_ID=\"$CONTAINER_ID\"/" scripts/github-mcp-connector.sh

测试连接器：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | bash scripts/github-mcp-connector.sh

内存库多容器问题

症状：多个 memory-bank-mcp:local 集装箱 docker ps -a

解决方案:

清理旧容器：

docker rm $(docker ps -aq --filter ancestor=memory-bank-mcp:local --filter status=exited)

更新的连接器脚本现在使用 --rm 标记以防止此问题

一般故障排除

如果您遇到其他问题：

检查设置的运行状况:
```
bash scripts/health-check.sh
```
查看日志:
```
cat logs/startup.log
```
验证MCP服务器注册:
```
claude mcp list
```
检查是否有过时的锁文件:
```
ls -la vscode-integration/.server-lock
```

重新启动服务器:

bash scripts/cleanup.sh
bash vscode-integration/start-servers.sh

克劳德代码与临床差异

如果MCP服务器在Cline/VS代码中工作，但在Claude代码中不工作：

检查stdio参数：确保连接器脚本通过 stdio MCP服务器的参数
验证JSON-RPC协议：使用手动JSON-RPC消息进行测试
容器法：Claude Code可能需要与VS Code扩展不同的连接方法

清理

要删除所有MCP服务器配置：

bash scripts/cleanup.sh

需求

码头工人：适用于GitHub MCP服务器和内存库MCP服务器
Node.js和npm：适用于Context7、浏览器工具、Puppeter和知识图谱MCP服务器
卷曲：用于健康检查和网络连接测试
VS代码：用于自动化启动集成

配置

GitHub令牌设置

前往GitHub设置>开发者设置>个人访问令牌
生成具有适当权限的新令牌

更新 .env 使用您的令牌：

export GITHUB_PERSONAL_ACCESS_TOKEN="your_actual_token_here"

存储体设置

存储库MCP服务器将数据存储在 data/memory-bank/。此目录会自动创建并挂载到Docker容器中。

知识图谱设置

知识图谱MCP服务器使用存储在 data/knowledge-graph/kg.db.

常见问题

Docker未运行

如果你看到“Docker未运行”错误：

# Start Docker Desktop
open -a Docker

权限不足

如果您遇到权限错误：

chmod +x scripts/*.sh vscode-integration/start-servers.sh
chmod 600 config/config.sh

找不到Node.js

如果未安装Node.js：

brew install node

MCP服务器未注册

检查Claude CLI是否已正确安装和配置：

claude mcp list

支持

有关特定MCP服务器的问题，请参阅其各自的文档：

使用说明

Claude MCP服务器配置

概述

全球MCP服务器集成

配置路径

标准配置格式

全球安装

安全最佳实践

健康检查

故障排除

跨平台兼容性

全局MCP配置

克劳德代码全局配置

Claude桌面配置

Cline.bot全局配置

常见配置选项

安全考虑

目录结构

快速开始

测试

VS代码集成

自动设置

运作原理

可用的MCP服务器

GitHub MCP服务器

Context7 MCP服务器

浏览器工具MCP服务器

木偶MCP服务器

存储库MCP服务器

知识图谱MCP服务器

安全考虑

维护

故障排除

常见问题的快速修复

GitHub MCP服务器连接失败

内存库多容器问题

一般故障排除

克劳德代码与临床差异

清理

需求

配置

GitHub令牌设置

存储体设置

知识图谱设置

常见问题

Docker未运行

权限不足

找不到Node.js

MCP服务器未注册

支持

相关 MCP

VSCode MCP桥接工具

AI助手协议服务器

GitHub MCP服务器

工作流协议服务器

GitHub代码上下文服务

Jotai MCP服务器