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.12（`run-server.sh`会自动优先探测`python3.12`，见 run-server.sh）
Git	用于`git clone`安装方式
uv	仅 uvx 安装方式需要，用于免本地依赖地直接运行
Windows 用户	使用 Claude Code CLI 需要 WSL2，详见 WSL 安装指南

从项目元数据看，pyproject.toml 声明requires-python = ">=3.9"，运行时依赖为mcp>=1.0.0、google-genai>=1.19.0、openai>=1.55.2、pydantic>=2.0.0、python-dotenv>=1.0.0，即官方文档的 Python 3.10+ 建议是兼容且更稳妥的选择。

二、Step 1：获取 API 密钥

PAL 至少需要一个可用 API 密钥才能工作。按需选择以下三种方式之一。

Option A：OpenRouter（新手推荐）

OpenRouter 用一个 API 即可访问多个模型（GPT、Claude、Gemini 等）。注册后在控制台生成 API key，并通过仪表盘控制消费额度。适合想快速体验、不想为每个厂商单独注册的用户。

Option B：原生提供商 API

Gemini（Google）：在 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.AI（Grok）：在 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 A：uvx 即时安装（推荐）

前置：先安装 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 git+https://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 git+https://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 git+https://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 git+https://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 git+https://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 Code）

PAL 可以运行在任何支持 MCP 的 GUI IDE 中，配置方式与上面的 CLI 示例一致——把客户端指向uvx启动器并设置必要的环境变量。

Cursor IDE

打开 Cursor →Settings（Cmd+,/Ctrl+,）→Integrations › Model Context Protocol (MCP)。
点击Add MCP Server，填入：
- Command：sh
- Args：-c以及上面的uvx启动循环
- Environment（示例）：
  - PATH=/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin
  - GEMINI_API_KEY=your_api_key_here
保存配置，Cursor 会在需要时按需启动 MCP 服务器。

Visual Studio Code（Claude Dev 扩展）

安装 Claude Dev 扩展（v0.6.0 或更高版本）。
打开命令面板（Cmd+Shift+P/Ctrl+Shift+P）→Claude: Configure MCP Servers→Add server。
按提示填入与上面相同的值：Command 为sh，Args 为-c加uvx启动循环，Environment 添加你需要的 API 密钥（如GEMINI_API_KEY、OPENAI_API_KEY）。
保存扩展生成的 JSON 片段，下次与 Claude 交互时 VS Code 会自动重载服务器。

Pro tip：如果嫌长循环麻烦，可以替换为单行命令uvx --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server，只需确保每个客户端环境里uvx都在 PATH 上即可。

Method B：Clone 源码安装

# 克隆仓库 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 --help

setup 脚本做了什么：

✅ 创建 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_KEY=your-gemini-api-key-here # 用于 Gemini 模型 OPENAI_API_KEY=your-openai-api-key-here # 用于 GPT-5.2、GPT-5.1-Codex、O3 XAI_API_KEY=your-xai-api-key-here # 用于 Grok 模型 OPENROUTER_API_KEY=your-openrouter-key # 用于多个模型 # DIAL 平台（可选） DIAL_API_KEY=your-dial-api-key-here DIAL_API_HOST=https://core.dialx.ai # 默认主机（可选） DIAL_API_VERSION=2024-12-01-preview # API 版本（可选） DIAL_ALLOWED_MODELS=o3,gemini-2.5-pro # 限制模型（可选） # 自定义/本地模型（Ollama、vLLM 等） CUSTOM_API_URL=http://localhost:11434/v1 # Ollama 示例 CUSTOM_API_KEY= # Ollama 留空 CUSTOM_MODEL_NAME=llama3.2 # 默认模型名

配置背后的实现原理

.env的加载由 utils/env.py 统一完成：模块启动时读取项目根目录的.env并调用load_dotenv；若在.env中设置PAL_MCP_FORCE_ENV_OVERRIDE=true，.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 Desktop

Claude 从 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 CLI

Codex 在~/.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 CLI

Gemini 在~/.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 models"

Claude Code CLI

退出已有 Claude 会话
在项目目录运行claude
尝试："Use pal to chat about Python best practices"

Gemini 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 repo"

OpenCode CLI

重启 OpenCode（或运行OpenCode: Reload Config）
打开Settings › Tools › MCP，确认pal已启用
开启新聊天，尝试："Use pal to list available models"

Codex 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_MODEL=auto时，服务器进入自动模式（见 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 found"

uvx 安装方式：

确保uv已安装并在 PATH 中
运行which uvx验证 uvx 可用
检查 PATH 是否包含/usr/local/bin和~/.local/bin

clone 安装方式：

重新运行./run-server.sh验证安装
检查虚拟环境：which python应显示.pal_venv/bin/python

API 密钥问题

"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_MODEL=auto GEMINI_API_KEY=your-key OPENAI_API_KEY=your-key GOOGLE_ALLOWED_MODELS=flash,pro OPENAI_ALLOWED_MODELS=gpt-5.1-codex-mini,gpt-5-mini,o4-mini

成本优化型

DEFAULT_MODEL=flash GEMINI_API_KEY=your-key GOOGLE_ALLOWED_MODELS=flash

高性能型

DEFAULT_MODEL=auto GEMINI_API_KEY=your-key OPENAI_API_KEY=your-key GOOGLE_ALLOWED_MODELS=pro OPENAI_ALLOWED_MODELS=gpt-5.1-codex,gpt-5.2

本地优先型

DEFAULT_MODEL=auto CUSTOM_API_URL=http://localhost:11434/v1 CUSTOM_MODEL_NAME=llama3.2 # 用云端 API 作后备 GEMINI_API_KEY=your-key

十、下一步

🎯 尝试主 README 中的示例工作流
📚 深入工具参考文档了解每个工具的能力
⚡ 阅读高级用法指南探索复杂工作流
🔧 查阅配置选项定制行为
💡 若需在多提供商间做精细权衡，可参考模型排行与选择；如需理解 Docker 部署，见 Docker 部署指南

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考