PAL MCP Server 从零入门安装、配置、多模型调用与故障排查完全指南【免费下载链接】pal-mcp-serverThe power of Claude Code / GeminiCLI / CodexCLI [Gemini / OpenAI / OpenRouter / Azure / Grok / Ollama / Custom Model / All Of The Above] working as one.项目地址: https://gitcode.com/GitHub_Trending/ge/pal-mcp-server本指南以 docs/getting-started.md 为主线完整讲解 PAL MCP Server 的从零起步流程前置环境准备、API 密钥获取、两种安装方式uvx 一键运行与源码 clone、各 AI 客户端的 MCP 接入配置、超时防护、安装验证、工具调用实战与常见故障排查。读完本文你将能把 Gemini / OpenAI / OpenRouter / Azure / Grok / Ollama / 自定义模型接入 Claude Code、Claude Desktop、Gemini CLI、Codex CLI、Qwen Code CLI、OpenCode 以及 Cursor、VS Code 等 MCP 客户端并立刻上手chat、thinkdeep、consensus、analyze等全部工具。一、前置条件在开始之前请确认你的环境满足以下要求条件说明Python 3.10推荐 3.12run-server.sh会自动优先探测python3.12见 run-server.shGit用于git clone安装方式uv仅 uvx 安装方式需要用于免本地依赖地直接运行Windows 用户使用 Claude Code CLI 需要 WSL2详见 WSL 安装指南从项目元数据看pyproject.toml 声明requires-python 3.9运行时依赖为mcp1.0.0、google-genai1.19.0、openai1.55.2、pydantic2.0.0、python-dotenv1.0.0即官方文档的 Python 3.10 建议是兼容且更稳妥的选择。二、Step 1获取 API 密钥PAL 至少需要一个可用 API 密钥才能工作。按需选择以下三种方式之一。Option AOpenRouter新手推荐OpenRouter 用一个 API 即可访问多个模型GPT、Claude、Gemini 等。注册后在控制台生成 API key并通过仪表盘控制消费额度。适合想快速体验、不想为每个厂商单独注册的用户。Option B原生提供商 APIGeminiGoogle在 Google AI Studio 生成 API key。注意Gemini 3.0 / 2.5 Pro 建议使用付费 key免费额度访问受限。OpenAI在 OpenAI Platform 生成 API key用于访问 GPT-5.2、GPT-5.1-Codex、GPT-5、O3 等模型。X.AIGrok在 X.AI Console 生成 API key。DIAL 平台在 DIAL Platform 生成 key可获得厂商无关的模型访问能力。Option C本地模型免费Ollama 三步启动# 安装 Ollama curl -fsSL https://ollama.ai/install.sh | sh # 启动 Ollama 服务 ollama serve # 拉取模型例如 Llama 3.2 ollama pull llama3.2其他本地选项还包括vLLM自托管推理服务、LM Studio提供 OpenAI 兼容 API 的本地模型托管、Text Generation WebUI等。本地模型的完整接入细节URL、模型名、能力声明见 自定义模型指南。仓库中 conf/custom_models.json 展示了本地模型元数据的标准写法例如llama3.2声明了context_window: 128000、别名local-llama/ollama-llama、supports_function_calling: false等字段。三、Step 2安装有两种安装方式按你的使用习惯选择。Method Auvx 即时安装推荐前置先安装 uv。uvx 方式的核心价值是✅ 零手动设置✅ 总是拉取最新版本✅ 无需管理本地依赖✅ 无需提前配置 Python 环境uvx直接以--from git...方式从源码仓库启动服务。下面是各 AI 客户端的接入配置。Claude Desktop打开 Claude Desktop → Settings → Developer → Edit Config加入{ mcpServers: { pal: { command: sh, args: [ -c, for p in $(which uvx 2/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \$p\ ] exec \$p\ --from githttps://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo uvx not found 2; exit 1 ], env: { PATH: /usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin, GEMINI_API_KEY: your_api_key_here } } } }Claude Code CLI在项目根目录创建.mcp.json{ mcpServers: { pal: { command: sh, args: [ -c, for p in $(which uvx 2/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \$p\ ] exec \$p\ --from githttps://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo uvx not found 2; exit 1 ], env: { PATH: /usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin, GEMINI_API_KEY: your_api_key_here } } } }Gemini CLI编辑~/.gemini/settings.json{ mcpServers: { pal: { command: sh, args: [ -c, for p in $(which uvx 2/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \$p\ ] exec \$p\ --from githttps://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo uvx not found 2; exit 1 ], env: { PATH: /usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin, GEMINI_API_KEY: your_api_key_here } } } }Codex CLI编辑~/.codex/config.toml[mcp_servers.pal] command bash args [-c, for p in $(which uvx 2/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \$p\ ] exec \$p\ --from githttps://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo uvx not found 2; exit 1] tool_timeout_sec 1200 # 20 minutes; added automatically by the setup script so upstream providers can respond [mcp_servers.pal.env] PATH /usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:$HOME/.local/bin:$HOME/.cargo/bin:$HOME/bin GEMINI_API_KEY your_api_key_here同时启用 Codex 内置的 web-search 工具使 PAL 的apilookup指令能正常执行[tools] web_search true如果文件中没有[tools]段把上面的块追加进去否则确保该段中已包含web_search true。Qwen Code CLI创建或编辑~/.qwen/settings.json{ mcpServers: { pal: { command: bash, args: [ -c, for p in $(which uvx 2/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \$p\ ] exec \$p\ --from githttps://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo uvx not found 2; exit 1 ], cwd: /path/to/pal-mcp-server, env: { PATH: /usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin, GEMINI_API_KEY: your_api_key_here } } } }把占位 API key 换成你实际使用的提供商密钥Gemini、OpenAI、OpenRouter 等。OpenCode CLI编辑~/.config/opencode/opencode.json此方式直接使用本地克隆的 venv 运行 server.py{ $schema: https://opencode.ai/config.json, mcp: { pal: { type: local, command: [ /path/to/pal-mcp-server/.pal_venv/bin/python, /path/to/pal-mcp-server/server.py ], cwd: /path/to/pal-mcp-server, enabled: true, environment: { GEMINI_API_KEY: your_api_key_here } } } }同样可按需追加OPENAI_API_KEY、OPENROUTER_API_KEY等其他密钥。server.py即 MCP 服务的入口模块内部通过mcp.server.stdio以 stdio 方式与客户端通信并在启动时注册 18 个工具chat、thinkdeep、planner、consensus、analyze、codereview、debug、precommit、refactor、testgen、secaudit、docgen、challenge、tracer、listmodels、version等详见 server.py 与 tools/init.py。IDE 客户端Cursor 与 VS CodePAL 可以运行在任何支持 MCP 的 GUI IDE 中配置方式与上面的 CLI 示例一致——把客户端指向uvx启动器并设置必要的环境变量。Cursor IDE打开 Cursor →SettingsCmd,/Ctrl,→Integrations › Model Context Protocol (MCP)。点击Add MCP Server填入CommandshArgs-c以及上面的uvx启动循环Environment示例PATH/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/binGEMINI_API_KEYyour_api_key_here保存配置Cursor 会在需要时按需启动 MCP 服务器。Visual Studio CodeClaude Dev 扩展安装 Claude Dev 扩展v0.6.0 或更高版本。打开命令面板CmdShiftP/CtrlShiftP→Claude: Configure MCP Servers→Add server。按提示填入与上面相同的值Command 为shArgs 为-c加uvx启动循环Environment 添加你需要的 API 密钥如GEMINI_API_KEY、OPENAI_API_KEY。保存扩展生成的 JSON 片段下次与 Claude 交互时 VS Code 会自动重载服务器。Pro tip如果嫌长循环麻烦可以替换为单行命令uvx --from githttps://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server只需确保每个客户端环境里uvx都在 PATH 上即可。Method BClone 源码安装# 克隆仓库 git clone https://github.com/BeehiveInnovations/pal-mcp-server.git cd pal-mcp-server # 一条命令完成全部设置 ./run-server.sh # 或使用 Windows PowerShell 版本 ./run-server.ps1 # 查看 Claude Desktop 配置 ./run-server.sh -c # 查看所有选项 ./run-server.sh --helpsetup 脚本做了什么✅ 创建 Python 虚拟环境run-server.sh会优先用 uv 创建找不到再回退系统 Python见 run-server.sh✅ 安装所有依赖mcp、google-genai、openai、pydantic、python-dotenv见 run-server.sh✅ 为 API 密钥创建.env文件基于.env.example复制并替换占位符见 run-server.sh✅ 配置 Claude 集成✅ 提供可复制的配置片段更新之后每次git pull后都请重新运行一次./run-server.sh确保依赖和配置同步。Windows 用户详细 WSL 配置请阅读 WSL 安装指南。四、Step 3配置 API 密钥uvx 安装方式直接把 API 密钥写进上文各客户端的 MCP 配置中。clone 安装方式编辑.env文件nano .env加入至少一个 API 密钥# 选择你的提供商至少需要一个 GEMINI_API_KEYyour-gemini-api-key-here # 用于 Gemini 模型 OPENAI_API_KEYyour-openai-api-key-here # 用于 GPT-5.2、GPT-5.1-Codex、O3 XAI_API_KEYyour-xai-api-key-here # 用于 Grok 模型 OPENROUTER_API_KEYyour-openrouter-key # 用于多个模型 # DIAL 平台可选 DIAL_API_KEYyour-dial-api-key-here DIAL_API_HOSThttps://core.dialx.ai # 默认主机可选 DIAL_API_VERSION2024-12-01-preview # API 版本可选 DIAL_ALLOWED_MODELSo3,gemini-2.5-pro # 限制模型可选 # 自定义/本地模型Ollama、vLLM 等 CUSTOM_API_URLhttp://localhost:11434/v1 # Ollama 示例 CUSTOM_API_KEY # Ollama 留空 CUSTOM_MODEL_NAMEllama3.2 # 默认模型名配置背后的实现原理.env的加载由 utils/env.py 统一完成模块启动时读取项目根目录的.env并调用load_dotenv若在.env中设置PAL_MCP_FORCE_ENV_OVERRIDEtrue.env的值将覆盖已存在的系统环境变量见 utils/env.py。模型与提供商的路由由 providers/registry.py 的ModelProviderRegistry管理。注册表按固定优先级解析模型归属GOOGLE → OPENAI → AZURE → XAI → DIAL → CUSTOM → OPENROUTER见 providers/registry.py这正是原文档中多个 API 配置时原生 API 优先于 OpenRouter这一规则对应的源码实现。只有配置了有效 API key 的提供商才会被实例化并对外暴露模型见 providers/registry.py。各提供商的模型目录含别名、上下文窗口、能力标记集中维护在conf/下的 JSON 清单中gemini_models.json、openai_models.json、xai_models.json、openrouter_models.json、dial_models.json、custom_models.json并可用对应的*_MODELS_CONFIG_PATH环境变量指向自定义副本详见 配置参考。模型的别名配置在conf/custom_models.json原文档写作../conf/custom_models.json已按仓库根目录换算。五、防止客户端超时部分 MCP 客户端默认超时很短运行长耗时工具时可能中断与 PAL 的连接。建议为每个客户端设置充足的上限官方推荐至少 5 分钟PAL 的 setup 脚本还会为 Codex 写入 20 分钟的工具超时以便上游提供商有足够时间响应。Claude Code 与 Claude DesktopClaude 从 shell 或~/.claude/settings.json读取 MCP 相关环境变量。添加或更新env块让启动与工具执行都使用 5 分钟上限{ env: { MCP_TIMEOUT: 300000, MCP_TOOL_TIMEOUT: 300000 } }该块可以放在settings.json顶层作用于所有会话也可以放在某个mcpServers.name.env下只对 PAL 生效服务器名在配置迁移期间可能仍为pal。数值单位为毫秒。注意Claude 的 SSE 传输仍有约 5 分钟的内部上限长时间运行的 HTTP/SSE 服务器可能需要重试直到 Anthropic 修复该问题。Codex CLICodex 在~/.codex/config.toml中提供按服务器设置的超时。在[[mcp_servers.name]]下添加或调大这些键[mcp_servers.pal] command ... args [...] startup_timeout_sec 300 # 默认 10 秒 tool_timeout_sec 1200 # 默认 60 秒setup 脚本预置 20 分钟以便上游提供商响应startup_timeout_sec覆盖初始握手/列工具阶段tool_timeout_sec则约束每次工具调用。如果 MCP 服务器调用的上游提供商经常需要超过 20 分钟请调大后者。Gemini CLIGemini 在~/.gemini/settings.json中为每个服务器使用单一timeout字段设置为至少 5 分钟单位毫秒{ mcpServers: { pal: { command: uvx, args: [pal-mcp-server], timeout: 300000 } } }注意0.2.1 及更新版本在某些传输上存在已知回归会忽略约 60 秒以上的值如果仍出现提前断开建议把任务拆小或关注 Gemini CLI 的版本更新。重要提示⭐无需重启——修改立即生效⭐ 若配置了多个 API原生 API 优先于 OpenRouter对应 providers/registry.py 的优先级顺序⭐ 模型别名在conf/custom_models.json中配置六、Step 4测试安装Claude Desktop重启 Claude Desktop打开新对话尝试Use pal to list available modelsClaude Code CLI退出已有 Claude 会话在项目目录运行claude尝试Use pal to chat about Python best practicesGemini CLI注意PAL MCP 可以连接 Gemini CLI但工具调用目前尚不完全正常请参阅 Gemini CLI 安装说明 获取最新进展。Qwen Code CLI若正在运行则先退出qwen exit运行qwen mcp list --scope user确认pal显示CONNECTED尝试/mcp查看可用工具或Use pal to analyze this repoOpenCode CLI重启 OpenCode或运行OpenCode: Reload Config打开Settings › Tools › MCP确认pal已启用开启新聊天尝试Use pal to list available modelsCodex CLI若正在运行则重启 Codex CLI打开新对话尝试Use pal to list available models通用测试命令Use pal to list available models Chat with pal about the best approach for API design Use pal thinkdeep with gemini pro about scaling strategies Debug this error with o3: [paste error]提示使用 setup 脚本时Codex CLI 提供出色的 MCP 集成会自动配置环境变量。listmodels工具会通过 providers/registry.py 的get_available_models/get_available_model_names枚举所有已启用提供商的模型——即只列出配置了有效 API key 的提供商所支持的模型并自动遵循*_ALLOWED_MODELS等限制规则。因此用它排查模型不可用问题非常有效。七、Step 5开始使用 PAL基础用法模式让 Claude 自动选模型Use pal to analyze this code for security issues Debug this race condition with pal Plan the database migration with pal显式指定模型Use pal with gemini pro to review this complex algorithm Debug with o3 using pal for logical analysis Get flash to quickly format this code via pal多模型工作流Use pal to get consensus from pro and o3 on this architecture Code review with gemini, then precommit validation with o3 Analyze with flash, then deep dive with pro if issues found当DEFAULT_MODELauto时服务器进入自动模式见 config.py 的IS_AUTO_MODE由 Claude 根据任务在已启用提供商提供的模型池中挑选最合适的模型。快速工具参考 协作chat、thinkdeep、planner、consensus 代码分析analyze、codereview、debug、precommit⚒️ 开发refactor、testgen、secaudit、docgen 工具challenge、tracer、listmodels、version完整工具参考含详细示例与参数见 工具文档目录。这些工具在 tools/init.py 中统一导出并由 server.py 注册到 MCP 服务。八、常见问题与解决方案pal not found 或 command not founduvx 安装方式确保uv已安装并在 PATH 中运行which uvx验证 uvx 可用检查 PATH 是否包含/usr/local/bin和~/.local/binclone 安装方式重新运行./run-server.sh验证安装检查虚拟环境which python应显示.pal_venv/bin/pythonAPI 密钥问题Invalid API key 错误核对.env文件或 MCP 配置中的 API 密钥先用提供商自己的 API 直接测试密钥检查密钥前后是否有多余空格或引号Model not available运行Use pal to list available models查看已配置的模型检查环境变量中的模型限制如GOOGLE_ALLOWED_MODELS、OPENAI_ALLOWED_MODELS确认 API 密钥对该模型有访问权限性能问题响应慢使用更快的模型flash替代pro降低思考模式用minimal或low替代high限制模型访问避免昂贵的模型被选中Token 超限错误使用上下文窗口更大的模型例如conf/gemini_models.json中 gemini-3-pro-preview 的 1M 上下文把大请求拆成小块参见 大提示词处理指南更多帮助 完整故障排查指南 高级用法指南 配置参考覆盖全部环境变量与模型清单说明九、快速配置模板开发环境均衡型DEFAULT_MODELauto GEMINI_API_KEYyour-key OPENAI_API_KEYyour-key GOOGLE_ALLOWED_MODELSflash,pro OPENAI_ALLOWED_MODELSgpt-5.1-codex-mini,gpt-5-mini,o4-mini成本优化型DEFAULT_MODELflash GEMINI_API_KEYyour-key GOOGLE_ALLOWED_MODELSflash高性能型DEFAULT_MODELauto GEMINI_API_KEYyour-key OPENAI_API_KEYyour-key GOOGLE_ALLOWED_MODELSpro OPENAI_ALLOWED_MODELSgpt-5.1-codex,gpt-5.2本地优先型DEFAULT_MODELauto CUSTOM_API_URLhttp://localhost:11434/v1 CUSTOM_MODEL_NAMEllama3.2 # 用云端 API 作后备 GEMINI_API_KEYyour-key十、下一步 尝试主 README 中的示例工作流 深入 工具参考文档 了解每个工具的能力⚡ 阅读 高级用法指南 探索复杂工作流 查阅 配置选项 定制行为 若需在多提供商间做精细权衡可参考 模型排行与选择如需理解 Docker 部署见 Docker 部署指南【免费下载链接】pal-mcp-serverThe power of Claude Code / GeminiCLI / CodexCLI [Gemini / OpenAI / OpenRouter / Azure / Grok / Ollama / Custom Model / All Of The Above] working as one.项目地址: https://gitcode.com/GitHub_Trending/ge/pal-mcp-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
PAL MCP Server 从零入门：安装、配置、多模型调用与故障排查完全指南
PAL MCP Server 从零入门安装、配置、多模型调用与故障排查完全指南【免费下载链接】pal-mcp-serverThe power of Claude Code / GeminiCLI / CodexCLI [Gemini / OpenAI / OpenRouter / Azure / Grok / Ollama / Custom Model / All Of The Above] working as one.项目地址: https://gitcode.com/GitHub_Trending/ge/pal-mcp-server本指南以 docs/getting-started.md 为主线完整讲解 PAL MCP Server 的从零起步流程前置环境准备、API 密钥获取、两种安装方式uvx 一键运行与源码 clone、各 AI 客户端的 MCP 接入配置、超时防护、安装验证、工具调用实战与常见故障排查。读完本文你将能把 Gemini / OpenAI / OpenRouter / Azure / Grok / Ollama / 自定义模型接入 Claude Code、Claude Desktop、Gemini CLI、Codex CLI、Qwen Code CLI、OpenCode 以及 Cursor、VS Code 等 MCP 客户端并立刻上手chat、thinkdeep、consensus、analyze等全部工具。一、前置条件在开始之前请确认你的环境满足以下要求条件说明Python 3.10推荐 3.12run-server.sh会自动优先探测python3.12见 run-server.shGit用于git clone安装方式uv仅 uvx 安装方式需要用于免本地依赖地直接运行Windows 用户使用 Claude Code CLI 需要 WSL2详见 WSL 安装指南从项目元数据看pyproject.toml 声明requires-python 3.9运行时依赖为mcp1.0.0、google-genai1.19.0、openai1.55.2、pydantic2.0.0、python-dotenv1.0.0即官方文档的 Python 3.10 建议是兼容且更稳妥的选择。二、Step 1获取 API 密钥PAL 至少需要一个可用 API 密钥才能工作。按需选择以下三种方式之一。Option AOpenRouter新手推荐OpenRouter 用一个 API 即可访问多个模型GPT、Claude、Gemini 等。注册后在控制台生成 API key并通过仪表盘控制消费额度。适合想快速体验、不想为每个厂商单独注册的用户。Option B原生提供商 APIGeminiGoogle在 Google AI Studio 生成 API key。注意Gemini 3.0 / 2.5 Pro 建议使用付费 key免费额度访问受限。OpenAI在 OpenAI Platform 生成 API key用于访问 GPT-5.2、GPT-5.1-Codex、GPT-5、O3 等模型。X.AIGrok在 X.AI Console 生成 API key。DIAL 平台在 DIAL Platform 生成 key可获得厂商无关的模型访问能力。Option C本地模型免费Ollama 三步启动# 安装 Ollama curl -fsSL https://ollama.ai/install.sh | sh # 启动 Ollama 服务 ollama serve # 拉取模型例如 Llama 3.2 ollama pull llama3.2其他本地选项还包括vLLM自托管推理服务、LM Studio提供 OpenAI 兼容 API 的本地模型托管、Text Generation WebUI等。本地模型的完整接入细节URL、模型名、能力声明见 自定义模型指南。仓库中 conf/custom_models.json 展示了本地模型元数据的标准写法例如llama3.2声明了context_window: 128000、别名local-llama/ollama-llama、supports_function_calling: false等字段。三、Step 2安装有两种安装方式按你的使用习惯选择。Method Auvx 即时安装推荐前置先安装 uv。uvx 方式的核心价值是✅ 零手动设置✅ 总是拉取最新版本✅ 无需管理本地依赖✅ 无需提前配置 Python 环境uvx直接以--from git...方式从源码仓库启动服务。下面是各 AI 客户端的接入配置。Claude Desktop打开 Claude Desktop → Settings → Developer → Edit Config加入{ mcpServers: { pal: { command: sh, args: [ -c, for p in $(which uvx 2/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \$p\ ] exec \$p\ --from githttps://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo uvx not found 2; exit 1 ], env: { PATH: /usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin, GEMINI_API_KEY: your_api_key_here } } } }Claude Code CLI在项目根目录创建.mcp.json{ mcpServers: { pal: { command: sh, args: [ -c, for p in $(which uvx 2/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \$p\ ] exec \$p\ --from githttps://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo uvx not found 2; exit 1 ], env: { PATH: /usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin, GEMINI_API_KEY: your_api_key_here } } } }Gemini CLI编辑~/.gemini/settings.json{ mcpServers: { pal: { command: sh, args: [ -c, for p in $(which uvx 2/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \$p\ ] exec \$p\ --from githttps://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo uvx not found 2; exit 1 ], env: { PATH: /usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin, GEMINI_API_KEY: your_api_key_here } } } }Codex CLI编辑~/.codex/config.toml[mcp_servers.pal] command bash args [-c, for p in $(which uvx 2/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \$p\ ] exec \$p\ --from githttps://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo uvx not found 2; exit 1] tool_timeout_sec 1200 # 20 minutes; added automatically by the setup script so upstream providers can respond [mcp_servers.pal.env] PATH /usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:$HOME/.local/bin:$HOME/.cargo/bin:$HOME/bin GEMINI_API_KEY your_api_key_here同时启用 Codex 内置的 web-search 工具使 PAL 的apilookup指令能正常执行[tools] web_search true如果文件中没有[tools]段把上面的块追加进去否则确保该段中已包含web_search true。Qwen Code CLI创建或编辑~/.qwen/settings.json{ mcpServers: { pal: { command: bash, args: [ -c, for p in $(which uvx 2/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \$p\ ] exec \$p\ --from githttps://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo uvx not found 2; exit 1 ], cwd: /path/to/pal-mcp-server, env: { PATH: /usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin, GEMINI_API_KEY: your_api_key_here } } } }把占位 API key 换成你实际使用的提供商密钥Gemini、OpenAI、OpenRouter 等。OpenCode CLI编辑~/.config/opencode/opencode.json此方式直接使用本地克隆的 venv 运行 server.py{ $schema: https://opencode.ai/config.json, mcp: { pal: { type: local, command: [ /path/to/pal-mcp-server/.pal_venv/bin/python, /path/to/pal-mcp-server/server.py ], cwd: /path/to/pal-mcp-server, enabled: true, environment: { GEMINI_API_KEY: your_api_key_here } } } }同样可按需追加OPENAI_API_KEY、OPENROUTER_API_KEY等其他密钥。server.py即 MCP 服务的入口模块内部通过mcp.server.stdio以 stdio 方式与客户端通信并在启动时注册 18 个工具chat、thinkdeep、planner、consensus、analyze、codereview、debug、precommit、refactor、testgen、secaudit、docgen、challenge、tracer、listmodels、version等详见 server.py 与 tools/init.py。IDE 客户端Cursor 与 VS CodePAL 可以运行在任何支持 MCP 的 GUI IDE 中配置方式与上面的 CLI 示例一致——把客户端指向uvx启动器并设置必要的环境变量。Cursor IDE打开 Cursor →SettingsCmd,/Ctrl,→Integrations › Model Context Protocol (MCP)。点击Add MCP Server填入CommandshArgs-c以及上面的uvx启动循环Environment示例PATH/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/binGEMINI_API_KEYyour_api_key_here保存配置Cursor 会在需要时按需启动 MCP 服务器。Visual Studio CodeClaude Dev 扩展安装 Claude Dev 扩展v0.6.0 或更高版本。打开命令面板CmdShiftP/CtrlShiftP→Claude: Configure MCP Servers→Add server。按提示填入与上面相同的值Command 为shArgs 为-c加uvx启动循环Environment 添加你需要的 API 密钥如GEMINI_API_KEY、OPENAI_API_KEY。保存扩展生成的 JSON 片段下次与 Claude 交互时 VS Code 会自动重载服务器。Pro tip如果嫌长循环麻烦可以替换为单行命令uvx --from githttps://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server只需确保每个客户端环境里uvx都在 PATH 上即可。Method BClone 源码安装# 克隆仓库 git clone https://github.com/BeehiveInnovations/pal-mcp-server.git cd pal-mcp-server # 一条命令完成全部设置 ./run-server.sh # 或使用 Windows PowerShell 版本 ./run-server.ps1 # 查看 Claude Desktop 配置 ./run-server.sh -c # 查看所有选项 ./run-server.sh --helpsetup 脚本做了什么✅ 创建 Python 虚拟环境run-server.sh会优先用 uv 创建找不到再回退系统 Python见 run-server.sh✅ 安装所有依赖mcp、google-genai、openai、pydantic、python-dotenv见 run-server.sh✅ 为 API 密钥创建.env文件基于.env.example复制并替换占位符见 run-server.sh✅ 配置 Claude 集成✅ 提供可复制的配置片段更新之后每次git pull后都请重新运行一次./run-server.sh确保依赖和配置同步。Windows 用户详细 WSL 配置请阅读 WSL 安装指南。四、Step 3配置 API 密钥uvx 安装方式直接把 API 密钥写进上文各客户端的 MCP 配置中。clone 安装方式编辑.env文件nano .env加入至少一个 API 密钥# 选择你的提供商至少需要一个 GEMINI_API_KEYyour-gemini-api-key-here # 用于 Gemini 模型 OPENAI_API_KEYyour-openai-api-key-here # 用于 GPT-5.2、GPT-5.1-Codex、O3 XAI_API_KEYyour-xai-api-key-here # 用于 Grok 模型 OPENROUTER_API_KEYyour-openrouter-key # 用于多个模型 # DIAL 平台可选 DIAL_API_KEYyour-dial-api-key-here DIAL_API_HOSThttps://core.dialx.ai # 默认主机可选 DIAL_API_VERSION2024-12-01-preview # API 版本可选 DIAL_ALLOWED_MODELSo3,gemini-2.5-pro # 限制模型可选 # 自定义/本地模型Ollama、vLLM 等 CUSTOM_API_URLhttp://localhost:11434/v1 # Ollama 示例 CUSTOM_API_KEY # Ollama 留空 CUSTOM_MODEL_NAMEllama3.2 # 默认模型名配置背后的实现原理.env的加载由 utils/env.py 统一完成模块启动时读取项目根目录的.env并调用load_dotenv若在.env中设置PAL_MCP_FORCE_ENV_OVERRIDEtrue.env的值将覆盖已存在的系统环境变量见 utils/env.py。模型与提供商的路由由 providers/registry.py 的ModelProviderRegistry管理。注册表按固定优先级解析模型归属GOOGLE → OPENAI → AZURE → XAI → DIAL → CUSTOM → OPENROUTER见 providers/registry.py这正是原文档中多个 API 配置时原生 API 优先于 OpenRouter这一规则对应的源码实现。只有配置了有效 API key 的提供商才会被实例化并对外暴露模型见 providers/registry.py。各提供商的模型目录含别名、上下文窗口、能力标记集中维护在conf/下的 JSON 清单中gemini_models.json、openai_models.json、xai_models.json、openrouter_models.json、dial_models.json、custom_models.json并可用对应的*_MODELS_CONFIG_PATH环境变量指向自定义副本详见 配置参考。模型的别名配置在conf/custom_models.json原文档写作../conf/custom_models.json已按仓库根目录换算。五、防止客户端超时部分 MCP 客户端默认超时很短运行长耗时工具时可能中断与 PAL 的连接。建议为每个客户端设置充足的上限官方推荐至少 5 分钟PAL 的 setup 脚本还会为 Codex 写入 20 分钟的工具超时以便上游提供商有足够时间响应。Claude Code 与 Claude DesktopClaude 从 shell 或~/.claude/settings.json读取 MCP 相关环境变量。添加或更新env块让启动与工具执行都使用 5 分钟上限{ env: { MCP_TIMEOUT: 300000, MCP_TOOL_TIMEOUT: 300000 } }该块可以放在settings.json顶层作用于所有会话也可以放在某个mcpServers.name.env下只对 PAL 生效服务器名在配置迁移期间可能仍为pal。数值单位为毫秒。注意Claude 的 SSE 传输仍有约 5 分钟的内部上限长时间运行的 HTTP/SSE 服务器可能需要重试直到 Anthropic 修复该问题。Codex CLICodex 在~/.codex/config.toml中提供按服务器设置的超时。在[[mcp_servers.name]]下添加或调大这些键[mcp_servers.pal] command ... args [...] startup_timeout_sec 300 # 默认 10 秒 tool_timeout_sec 1200 # 默认 60 秒setup 脚本预置 20 分钟以便上游提供商响应startup_timeout_sec覆盖初始握手/列工具阶段tool_timeout_sec则约束每次工具调用。如果 MCP 服务器调用的上游提供商经常需要超过 20 分钟请调大后者。Gemini CLIGemini 在~/.gemini/settings.json中为每个服务器使用单一timeout字段设置为至少 5 分钟单位毫秒{ mcpServers: { pal: { command: uvx, args: [pal-mcp-server], timeout: 300000 } } }注意0.2.1 及更新版本在某些传输上存在已知回归会忽略约 60 秒以上的值如果仍出现提前断开建议把任务拆小或关注 Gemini CLI 的版本更新。重要提示⭐无需重启——修改立即生效⭐ 若配置了多个 API原生 API 优先于 OpenRouter对应 providers/registry.py 的优先级顺序⭐ 模型别名在conf/custom_models.json中配置六、Step 4测试安装Claude Desktop重启 Claude Desktop打开新对话尝试Use pal to list available modelsClaude Code CLI退出已有 Claude 会话在项目目录运行claude尝试Use pal to chat about Python best practicesGemini CLI注意PAL MCP 可以连接 Gemini CLI但工具调用目前尚不完全正常请参阅 Gemini CLI 安装说明 获取最新进展。Qwen Code CLI若正在运行则先退出qwen exit运行qwen mcp list --scope user确认pal显示CONNECTED尝试/mcp查看可用工具或Use pal to analyze this repoOpenCode CLI重启 OpenCode或运行OpenCode: Reload Config打开Settings › Tools › MCP确认pal已启用开启新聊天尝试Use pal to list available modelsCodex CLI若正在运行则重启 Codex CLI打开新对话尝试Use pal to list available models通用测试命令Use pal to list available models Chat with pal about the best approach for API design Use pal thinkdeep with gemini pro about scaling strategies Debug this error with o3: [paste error]提示使用 setup 脚本时Codex CLI 提供出色的 MCP 集成会自动配置环境变量。listmodels工具会通过 providers/registry.py 的get_available_models/get_available_model_names枚举所有已启用提供商的模型——即只列出配置了有效 API key 的提供商所支持的模型并自动遵循*_ALLOWED_MODELS等限制规则。因此用它排查模型不可用问题非常有效。七、Step 5开始使用 PAL基础用法模式让 Claude 自动选模型Use pal to analyze this code for security issues Debug this race condition with pal Plan the database migration with pal显式指定模型Use pal with gemini pro to review this complex algorithm Debug with o3 using pal for logical analysis Get flash to quickly format this code via pal多模型工作流Use pal to get consensus from pro and o3 on this architecture Code review with gemini, then precommit validation with o3 Analyze with flash, then deep dive with pro if issues found当DEFAULT_MODELauto时服务器进入自动模式见 config.py 的IS_AUTO_MODE由 Claude 根据任务在已启用提供商提供的模型池中挑选最合适的模型。快速工具参考 协作chat、thinkdeep、planner、consensus 代码分析analyze、codereview、debug、precommit⚒️ 开发refactor、testgen、secaudit、docgen 工具challenge、tracer、listmodels、version完整工具参考含详细示例与参数见 工具文档目录。这些工具在 tools/init.py 中统一导出并由 server.py 注册到 MCP 服务。八、常见问题与解决方案pal not found 或 command not founduvx 安装方式确保uv已安装并在 PATH 中运行which uvx验证 uvx 可用检查 PATH 是否包含/usr/local/bin和~/.local/binclone 安装方式重新运行./run-server.sh验证安装检查虚拟环境which python应显示.pal_venv/bin/pythonAPI 密钥问题Invalid API key 错误核对.env文件或 MCP 配置中的 API 密钥先用提供商自己的 API 直接测试密钥检查密钥前后是否有多余空格或引号Model not available运行Use pal to list available models查看已配置的模型检查环境变量中的模型限制如GOOGLE_ALLOWED_MODELS、OPENAI_ALLOWED_MODELS确认 API 密钥对该模型有访问权限性能问题响应慢使用更快的模型flash替代pro降低思考模式用minimal或low替代high限制模型访问避免昂贵的模型被选中Token 超限错误使用上下文窗口更大的模型例如conf/gemini_models.json中 gemini-3-pro-preview 的 1M 上下文把大请求拆成小块参见 大提示词处理指南更多帮助 完整故障排查指南 高级用法指南 配置参考覆盖全部环境变量与模型清单说明九、快速配置模板开发环境均衡型DEFAULT_MODELauto GEMINI_API_KEYyour-key OPENAI_API_KEYyour-key GOOGLE_ALLOWED_MODELSflash,pro OPENAI_ALLOWED_MODELSgpt-5.1-codex-mini,gpt-5-mini,o4-mini成本优化型DEFAULT_MODELflash GEMINI_API_KEYyour-key GOOGLE_ALLOWED_MODELSflash高性能型DEFAULT_MODELauto GEMINI_API_KEYyour-key OPENAI_API_KEYyour-key GOOGLE_ALLOWED_MODELSpro OPENAI_ALLOWED_MODELSgpt-5.1-codex,gpt-5.2本地优先型DEFAULT_MODELauto CUSTOM_API_URLhttp://localhost:11434/v1 CUSTOM_MODEL_NAMEllama3.2 # 用云端 API 作后备 GEMINI_API_KEYyour-key十、下一步 尝试主 README 中的示例工作流 深入 工具参考文档 了解每个工具的能力⚡ 阅读 高级用法指南 探索复杂工作流 查阅 配置选项 定制行为 若需在多提供商间做精细权衡可参考 模型排行与选择如需理解 Docker 部署见 Docker 部署指南【免费下载链接】pal-mcp-serverThe power of Claude Code / GeminiCLI / CodexCLI [Gemini / OpenAI / OpenRouter / Azure / Grok / Ollama / Custom Model / All Of The Above] working as one.项目地址: https://gitcode.com/GitHub_Trending/ge/pal-mcp-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考