/ 目錄 / 演練場 / mcp-agent
← 全部伺服器 ↗ GitHub
● 社群 lastmile-ai ⚡ 即開即用

mcp-agent

作者 lastmile-ai · lastmile-ai/mcp-agent

在 MCP 之上實現生產級 Agent 模式（Orchestrator、Router、Evaluator、Swarm），並可選用 Temporal 提供持久化保障。

來自 lastmile-ai 的 mcp-agent 是一個 Python 框架，使用成熟模式組合 MCP 型 Agent：Parallel、Router、Intent Classifier、Orchestrator-Workers、Deep Research、Evaluator-Optimizer、Swarm。無論使用 asyncio 還是 Temporal 進行持久化執行，API 保持一致。

▶ 觀看演示 📦 安裝 💡 使用場景

為什麼要用

核心特性

即時演示

實際使用效果

mcp-agent.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示，然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mcp-agent",
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列，而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "mcp-agent": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-agent"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add mcp-agent -- uvx mcp-agent

一行命令搞定。用 claude mcp list 驗證，claude mcp remove 移除。

使用場景

實戰用法： mcp-agent

為研究任務建立 orchestrator-workers Agent

👤 開發多步驟 Agent 的 Python 開發者 ⏱ ~60 min advanced

何時使用： 任務規模過大，無法由單次 LLM 處理，但可拆解為平行子任務（例如：研究 10 個競爭對手）。

前置條件
  • Python 3.10+ — standard
  • 你想讓 Agent 使用的 MCP 伺服器 — 在 mcp-agent 設定檔中列出它們
步驟
  1. 定義 Worker Agent
    建立 2 個 Agent — scraper 使用 firecrawl 伺服器，writer 使用 filesystem。為每個 Agent 設定專注的指令集。✓ 已複製
    → 兩個 Agent 實例
  2. 連接 Orchestrator
    使用 create_orchestrator(planner_llm=..., workers=[scraper, writer]) 將它們包裝起來。最大迭代次數設為 10。✓ 已複製
    → Orchestrator 回傳計畫及執行控制代碼
  3. 執行實際任務
    執行：「研究 GitHub 上評分最高的 5 個 Postgres MCP。為每個撰寫一頁摘要並存至 ./reports/<slug>.md。」✓ 已複製
    → 產生 5 個內容連貫的檔案

結果： 一個平行化 Agent，能在 3-5 分鐘內完成原本需要 30 分鐘手動多步驟操作的工作。

注意事項
  • Orchestrator 產生過多或過少的子任務 — 給規劃 LLM 明確的指引：「拆分為 3-7 個子任務，每個子任務工作量不超過 5 分鐘」
  • Worker 重複抓取相同資料 — 透過 app 狀態共用快取，或透過計畫明確傳遞結果
搭配使用： mcp-use · fastmcp

建立 evaluator-optimizer Agent 以產出高品質文案

👤 負責內容生產流程的團隊 ⏱ ~45 min advanced

何時使用： LLM 的初稿品質不足以直接上線。你需要一個自動「持續迭代直到通過」的迴圈。

步驟
  1. 定義撰稿者與評估者
    撰稿者：根據簡報產生草稿。評估者：以 [準確性、清晰度、語氣] 1-5 分評分，並附上評分理由。✓ 已複製
    → 兩個 Agent 定義完成
  2. 設定迴圈
    使用 EvaluatorOptimizer，所有評分標準的 min_rating=4，max_iterations=5。將簡報作為輸入傳入。✓ 已複製
    → 迴圈運行，迭代過程可在日誌中看到
  3. 觀察收斂情況
    針對 10 個不同的簡報，記錄：初始分數、最終分數、所需迭代次數。是否有從未收斂的簡報？✓ 已複製
    → 統計資料中標示出異常案例

結果： 無需人工審核即可產出品質一致的內容。

注意事項
  • 評估者過於寬鬆，迴圈在第 1 次迭代就以平庸的結果結束 — 校準評估者——在系統提示中提供 3 個範例輸入及預期分數
  • 當 max_iterations 設定過高時，費用暴增 — 上限設為 3-4 次；若仍無法收斂，問題在於簡報本身，而非模型

使用 Temporal 讓 Agent 工作流程具備持久性

👤 在生產環境中運行 Agent 的平台工程師 ⏱ ~90 min advanced

何時使用： 你的 Agent 流程執行時間較長（數分鐘至數小時），且無法承受節點故障後從頭重來的代價。

前置條件
  • 運行中的 Temporal 叢集 — 本地開發用 temporal server start-dev，生產環境用 Temporal Cloud 或自託管
步驟
  1. 標註工作流程
    在我現有的 orchestrator 函式上加上 @app.workflow 裝飾器，並在個別步驟上加上 @app.workflow_task。✓ 已複製
    → 工作流程已向 Temporal 註冊
  2. 切換執行器
    將 app 設定改為 executor: 'temporal'。註冊 Worker，並啟動一個工作流程。✓ 已複製
    → Temporal UI 顯示正在運行的工作流程
  3. 驗證崩潰復原
    在工作流程執行到一半時終止 Python Worker。重新啟動後，確認工作流程從最後一個完成的活動繼續執行。✓ 已複製
    → 沒有重複執行，沒有狀態遺失

結果： Agent 工作流程可以承受程序重啟、部署及 OOM——這對長達數小時的研究任務至關重要。

注意事項
  • 活動（Activity）不具冪等性，恢復執行導致重複寫入 — 每個活動必須能安全地重試——在對外部系統寫入時使用冪等性金鑰

組合

與其他 MCP 搭配，撬動十倍槓桿

mcp-agent + mcp-use

mcp-use 負責客戶端連線配置，mcp-agent 負責工作流程模式

使用 mcp-use 連接 filesystem 和 git，再以 mcp-agent 的 Orchestrator 包裝，規劃跨多個 repo 的重構任務。✓ 已複製
mcp-agent + fastmcp

用 FastMCP 建立自訂 MCP，供 mcp-agent 工作流程呼叫

透過 FastMCP 公開我們內部的排名 API，再在 mcp-agent Router 中使用它，對客戶問題進行分類。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
MCPApp config_path or config object 最頂層使用——每個程序一個實例 free
Agent(name, instruction, server_names) configured with which MCP servers it can use 定義每個 Worker 或角色 free
AugmentedLLM.generate / generate_str / generate_structured messages, optional schema 直接呼叫 LLM 並整合 MCP 工具 LLM tokens
create_parallel_llm / create_router_llm / create_orchestrator agents + planner LLM 實例化其中一種內建模式 LLM tokens × pattern fan-out
@app.workflow / @app.workflow_task decorator on async function 使用 Temporal 執行器時 free
EvaluatorOptimizer writer_agent, evaluator_agent, min_rating, max_iterations 對輸出品質要求嚴格時 expensive — cap max_iterations

成本與限制

運行它的成本

API 配額
mcp-agent 本身無配額限制；LLM 與 MCP 費用直接透傳
每次呼叫 Token 數
模式會放大 Token 用量——一個含 5 個 Worker 的 Parallel 模式，Token 消耗是單次 LLM 呼叫的 5 倍
費用
套件本身免費；LLM 費用與可選的 Temporal 基礎設施才是實際成本
提示
Orchestrator 等模式會產生扇出——在規劃 LLM 的系統提示中加入明確的 Token 預算限制

安全

權限、密鑰、影響範圍

憑證儲存： LLM 金鑰與各 MCP 密鑰使用環境變數儲存
資料出站： LLM 提供商 + 每個已設定的 MCP 伺服器 + Temporal（若已啟用）

故障排查

常見錯誤與修復

Workflow hangs at start with no logs

MCP 伺服器啟動失敗。在設定中啟用除錯日誌：logger: {level: 'DEBUG'}。通常是伺服器設定中的指令或環境變數有誤。

Orchestrator returns plan but no execution

你呼叫了 .plan() 而非 .generate()。請使用完整方法來執行計畫。

Temporal workflow fails with serialization error

你的活動回傳了無法序列化的物件（例如 MCP 客戶端控制代碼）。活動必須回傳可 JSON 序列化的值。

LLM ignores available tools and hallucinates

系統提示可能被截斷或缺少工具清單。升級至工具使用能力較強的模型（Sonnet、GPT-4o），並在執行前透過 list_tools 確認工具是否存在。

替代方案

mcp-agent 對比其他方案

替代方案何時用它替代權衡
mcp-use你只需要輕量的客戶端連線配置，不需要模式庫需要自行撰寫編排邏輯
LangGraph你需要具備時間旅行除錯功能的有狀態圖以 LangChain 為中心；MCP 支援屬於附加功能
CrewAI你想要有明確規範的角色型 Agent 團隊不同的思維模型；MCP 支援屬於次要功能

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills