MCPHost 🤖

一个命令行主机应用程序，使大型语言模型（LLMs）能够通过模型上下文协议（MCP）与外部工具交互。目前支持Claude、OpenAI、Google Gemini和Ollama模型。

在Discord上讨论该项目

目录

• 概述
• 功能
• 要求
• 环境设置
• 安装
• SDK 使用
• 配置
  • MCP 服务器
  • 环境变量替换
  • 简化配置模式
  • 工具过滤
  • 旧版配置支持
  • 传输类型
  • 系统提示
• 使用
  • 交互模式
  • 脚本模式
  • 钩子系统
  • 非交互模式
  • 模型生成参数
  • 可用模型
  • 示例
  • 标志
  • 认证子命令
  • 配置文件支持
  • 交互式命令
• 自动化与脚本
• MCP 服务器兼容性
• 贡献
• 许可证
• 致谢

概述 🌟

MCPHost 在 MCP 客户端-服务器架构中充当主机角色，其中：

• 主机（如 MCPHost）是管理连接和交互的 LLM 应用程序
• 客户端与 MCP 服务器保持一对一连接
• 服务器为 LLM 提供上下文、工具和能力

这种架构允许语言模型：

• 访问外部工具和数据源 🛠️
• 在多次交互中保持一致的上下文 🔄
• 安全地执行命令并获取信息 🔒

目前支持：

• Anthropic Claude 模型（Claude 3.5 Sonnet、Claude 3.5 Haiku 等）
• OpenAI 模型（GPT-4、GPT-4 Turbo、GPT-3.5 等）
• Google Gemini 模型（Gemini 2.0 Flash、Gemini 1.5 Pro 等）
• 任何支持函数调用的 Ollama 兼容模型
• 任何 OpenAI 兼容的 API 端点

功能 ✨

• 与多个 AI 模型进行交互式对话
• 非交互模式，用于脚本和自动化
• 脚本模式，用于基于 YAML 的可执行自动化脚本
• 支持多个并发的 MCP 服务器
• 工具过滤，可通过每个服务器的 allowedTools 和 excludedTools 进行配置
• 动态工具发现与集成
• 所有支持的模型均具备工具调用能力
• 可配置的 MCP 服务器位置和参数
• 跨模型类型的统一命令接口
• 可配置的消息历史窗口，用于管理上下文
• OAuth 认证支持 Anthropic（替代 API 密钥）
• 钩子系统，用于自定义集成和安全策略
• 配置和脚本中的环境变量替换
• 内置服务器，用于常见功能（文件系统、bash、待办事项、http）

要求 📋

• Go 1.23 或更高版本
• 对于 OpenAI/Anthropic：相应提供商的 API 密钥
• 对于 Ollama：本地安装的 Ollama 及所需模型
• 对于 Google/Gemini：Google API 密钥（详见 https://aistudio.google.com/app/apikey）
• 一个或多个与 MCP 兼容的工具服务器

环境设置 🔧

1. API 密钥：

# 适用于所有提供商（使用 --provider-api-key 标志或以下环境变量）
export OPENAI_API_KEY='your-openai-key'        # 用于 OpenAI
export ANTHROPIC_API_KEY='your-anthropic-key'  # 用于 Anthropic
export GOOGLE_API_KEY='your-google-key'        # 用于 Google/Gemini

2. Ollama 设置：

• 从 https://ollama.ai 安装 Ollama
• 拉取所需模型：

ollama pull mistral

• 确保 Ollama 正在运行：

ollama serve

您还可以使用标准环境变量配置 Ollama 客户端，例如 OLLAMA_HOST 用于 Ollama 基础 URL。

3. Google API 密钥（用于 Gemini）：

export GOOGLE_API_KEY='your-api-key'

4. OpenAI 兼容设置：

• 获取您的 API 服务器基础 URL、API 密钥和模型名称
• 使用 --provider-url 和 --provider-api-key 标志，或设置环境变量

5. 自签名证书（TLS）： 如果您使用的提供商采用自签名证书（例如本地 Ollama 使用 HTTPS），可以跳过证书验证：

mcphost --provider-url https://192.168.1.100:443 --tls-skip-verify

⚠️ 警告：仅在开发阶段或连接到受信任的自签名证书服务器时使用 --tls-skip-verify。这会禁用 TLS 证书验证，在生产环境中不安全。

安装 📦

go install github.com/mark3labs/mcphost@latest

SDK 使用 🛠️

MCPHost 还提供了一个 Go SDK，用于无需启动操作系统进程即可进行编程访问。该 SDK 与 CLI 保持完全相同的行为，包括配置加载、环境变量和默认值。

快速示例

package main

import (
    "context"
    "fmt"
    "github.com/mark3labs/mcphost/sdk"
)

func main() {
    ctx := context.Background()
    
    // 创建具有默认配置的 MCPHost 实例
    host, err := sdk.New(ctx, nil)
    if err != nil {
        panic(err)
    }
    defer host.Close()
    
    // 发送提示并获取响应
    response, err := host.Prompt(ctx, "2+2 是多少？")
    if err != nil {
        panic(err)
    }
    
    fmt.Println(response)
}

SDK 特性

• ✅ 无需启动进程即可进行编程访问
• ✅ 配置行为与 CLI 完全一致
• ✅ 会话管理（保存/加载/清除）
• ✅ 工具执行回调，用于监控
• ✅ 流式传输支持
• ✅ 与所有提供商和 MCP 服务器完全兼容

有关详细的 SDK 文档、示例和 API 参考，请参阅 SDK README。

配置 ⚙️

MCP 服务器

如果 MCPHost 的主目录中不存在配置文件，它将自动创建一个。它会按以下顺序查找配置文件：

• .mcphost.yml 或 .mcphost.json（首选）
• .mcp.yml 或 .mcp.json（向后兼容）

各操作系统上的配置文件位置：

• Linux/macOS：~/.mcphost.yml、~/.mcphost.json、~/.mcp.yml、~/.mcp.json
• Windows：%USERPROFILE%\.mcphost.yml、%USERPROFILE%\.mcphost.json、%USERPROFILE%\.mcp.yml、%USERPROFILE%\.mcp.json

您也可以使用 --config 标志指定自定义位置。

环境变量替换

MCPHost 支持在配置文件和脚本的 Frontmatter 中使用环境变量替换，语法如下：

• ${env://VAR} - 必需的环境变量（未设置时会失败）
• ${env://VAR:-default} - 可选的环境变量，带有默认值

这使得您可以将 API 密钥等敏感信息保存在环境变量中，同时保持配置的灵活性。

示例：

mcpServers:
  github:
    type: local
    command: ["docker", "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN=${env://GITHUB_TOKEN}", "ghcr.io/github/github-mcp-server"]
    environment:
      DEBUG: "${env://DEBUG:-false}"
      LOG_LEVEL: "${env://LOG_LEVEL:-info}"

model: "${env://MODEL:-anthropic/claude-sonnet-4-5-20250929}"
provider-api-key: "${env://OPENAI_API_KEY}"  # 必需 - 未设置时会失败

使用方法：

# 设置必需的环境变量
export GITHUB_TOKEN="ghp_your_token_here"
export OPENAI_API_KEY="your_openai_key"

# 可选地覆盖默认值
export DEBUG="true"
export MODEL="openai/gpt-4"

# 运行 mcphost
mcphost

简化配置模式

MCPHost 现在支持一种简化的配置模式，包含三种服务器类型：

本地服务器

用于在您的机器上运行命令的本地 MCP 服务器：

{
  "mcpServers": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "@modelcontextprotocol/server-filesystem", "${env://WORK_DIR:-/tmp}"],
      "environment": {
        "DEBUG": "${env://DEBUG:-false}",
        "LOG_LEVEL": "${env://LOG_LEVEL:-info}",
        "API_TOKEN": "${env://FS_API_TOKEN}"
      },
      "allowedTools": ["read_file", "write_file"],
      "excludedTools": ["delete_file"]
    },
    "github": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN=${env://GITHUB_TOKEN}", "ghcr.io/github/github-mcp-server"],
      "environment": {
        "DEBUG": "${env://DEBUG:-false}"
      }
    },
    "sqlite": {
      "type": "local",
      "command": ["uvx", "mcp-server-sqlite", "--db-path", "${env://DB_PATH:-/tmp/foo.db}"],
      "environment": {
        "SQLITE_DEBUG": "${env://DEBUG:-0}",
        "DATABASE_URL": "${env://DATABASE_URL:-sqlite:///tmp/foo.db}"
      }
    }
  }
}

每个本地服务器条目需要：

• type：必须设置为 "local"
• command：包含命令及其所有参数的数组
• environment：（可选）环境变量键值对对象
• allowedTools：（可选）要包含的工具名称数组（白名单）
• excludedTools：（可选）要排除的工具名称数组（黑名单）

远程服务器

用于通过 HTTP 访问的远程 MCP 服务器：

{
  "mcpServers": {
    "websearch": {
      "type": "remote",
      "url": "${env://WEBSEARCH_URL:-https://api.example.com/mcp}",
      "headers": ["Authorization: Bearer ${env://WEBSEARCH_TOKEN}"]
    },
    "weather": {
      "type": "remote", 
      "url": "${env://WEATHER_URL:-https://weather-mcp.example.com}"
    }
  }
}

每个远程服务器条目需要：

• type：必须设置为 "remote"
• url：MCP 服务器可访问的 URL
• headers：（可选）用于身份验证和其他自定义头的 HTTP 头数组

远程服务器会自动使用 StreamableHTTP 传输方式以获得最佳性能。

内置服务器

用于在进程中运行以获得最佳性能的内置 MCP 服务器：

{
  "mcpServers": {
    "filesystem": {
      "type": "builtin",
      "name": "fs",
      "options": {
        "allowed_directories": ["${env://WORK_DIR:-/tmp}", "${env://HOME}/documents"]
      },
      "allowedTools": ["read_file", "write_file", "list_directory"]
    },
    "filesystem-cwd": {
      "type": "builtin",
      "name": "fs"
    }
  }
}

每个内置服务器条目需要：

• type：必须设置为 "builtin"
• name：内置服务器的内部名称（例如，"fs" 表示文件系统）
• options：特定于内置服务器的配置选项

可用的内置服务器：

• fs（文件系统）：具有可配置允许目录的安全文件系统访问
  • allowed_directories：服务器可以访问的目录路径数组（未指定时默认为当前工作目录）
• bash：执行带有安全限制和超时控制的 Bash 命令
  • 无需任何配置选项
• todo：管理会话期间的任务跟踪临时待办事项列表
  • 无需任何配置选项（待办事项存储在内存中，重启后会重置）
• http：获取网页内容并将其转换为文本、Markdown 或 HTML 格式
  • 工具：fetch（获取并转换网页内容）、fetch_summarize（使用 AI 获取并总结网页内容）、fetch_extract（使用 AI 提取特定数据）、fetch_filtered_json（获取 JSON 并使用 gjson 路径语法进行过滤）
  • 无需任何配置选项

内置服务器示例

{
  "mcpServers": {
    "filesystem": {
      "type": "builtin",
      "name": "fs",
      "options": {
        "allowed_directories": ["/tmp", "/home/user/documents"]
      }
    },
    "bash-commands": {
      "type": "builtin", 
      "name": "bash"
    },
    "task-manager": {
      "type": "builtin",
      "name": "todo"
    },
    "web-fetcher": {
      "type": "builtin",
      "name": "http"
    }
  }
}

工具过滤

所有类型的 MCP 服务器都支持工具过滤，以限制可用的工具：

• allowedTools：白名单 - 仅允许服务器提供指定的工具
• excludedTools：黑名单 - 除指定工具外，其他所有工具均可使用

{
  "mcpServers": {
    "filesystem-readonly": {
      "type": "builtin",
      "name": "fs",
      "allowedTools": ["read_file", "list_directory"]
    },
    "filesystem-safe": {
      "type": "local", 
      "command": ["npx", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "excludedTools": ["delete_file"]
    }
  }
}

注意：allowedTools 和 excludedTools 是互斥的，每个服务器只能使用其中之一。

遗留配置支持

MCPHost 保持与先前配置格式的完全向后兼容性。注意：最近的一项错误修复提高了外部 MCP 服务器（Docker、NPX 等）的旧版 stdio 传输可靠性。

遗留 STDIO 格式

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/tmp/foo.db"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

遗留 SSE 格式

{
  "mcpServers": {
    "server_name": {
      "url": "http://some_host:8000/sse",
      "headers": ["Authorization: Bearer my-token"]
    }
  }
}

遗留 Docker/容器格式

{
  "mcpServers": {
    "phalcon": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mark3labs/phalcon-mcp:latest",
        "serve"
      ]
    }
  }
}

遗留可流式 HTTP 格式

{
  "mcpServers": {
    "websearch": {
      "transport": "streamable",
      "url": "https://api.example.com/mcp",
      "headers": ["Authorization: Bearer your-api-token"]
    }
  }
}

传输类型

MCPHost 支持四种传输类型：

• stdio：启动本地进程并通过 stdin/stdout 进行通信（用于 "local" 服务器）
• sse：使用 Server-Sent Events 连接到服务器（遗留格式）
• streamable：使用可流式 HTTP 协议连接到服务器（用于 "remote" 服务器）
• inprocess：在进程中运行内置服务器以获得最佳性能（用于 "builtin" 服务器）

简化后的模式会自动映射：

• "local" 类型 → stdio 传输
• "remote" 类型 → streamable 传输
• "builtin" 类型 → inprocess 传输

系统提示

您可以使用 --system-prompt 标志指定自定义系统提示。您可以通过以下两种方式之一：

1. 直接传递提示文本：

   mcphost --system-prompt "你是一位以友好语气回应的帮助型助手。"
   

2. 传递包含提示的文本文件路径：

   mcphost --system-prompt ./prompts/assistant.md
   

   示例 assistant.md 文件：

   你是一位有用编码助手。
   
   请：
   - 编写整洁易读的代码
   - 添加有用的注释
   - 遵循最佳实践
   - 解释你的思路
   

使用方法 🚀

MCPHost 是一个 CLI 工具，允许您通过统一的界面与各种 AI 模型交互。它通过 MCP 服务器支持多种工具，并且可以在交互式和非交互式模式下运行。

交互模式（默认）

开始一次交互式对话会话：

mcphost

脚本模式

运行支持变量替换的 YAML 基础自动化脚本：

# 使用 script 子命令
mcphost script myscript.sh

# 带有变量
mcphost script myscript.sh --args:directory /tmp --args:name "John"

# 直接执行（如果具有可执行权限且包含 shebang）
./myscript.sh

脚本格式

脚本将 YAML 配置与提示结合在一个可执行文件中。配置必须用 frontmatter 分隔符（---）包裹起来。您可以将提示包含在 YAML 配置中，也可以将其放在结束的 frontmatter 分隔符之后：

#!/usr/bin/env -S mcphost script
---
# 此脚本使用来自 https://github.com/dagger/container-use 的 container-use MCP 服务器
mcpServers:
  container-use:
    type: "local"
    command: ["cu", "stdio"]
prompt: |
  使用 Flask 和 FastAPI 创建两个简单的 Hello World 应用程序变体。每个应用都在各自的环境中运行。请给我这两个应用的 URL。
---

或者，您也可以省略 prompt: 字段，将提示放在 frontmatter 之后：

#!/usr/bin/env -S mcphost script
---
# 此脚本使用来自 https://github.com/dagger/container-use 的 container-use MCP 服务器
mcpServers:
  container-use:
    type: "local"
    command: ["cu", "stdio"]
---
使用 Flask 和 FastAPI 创建两个简单的 Hello World 应用程序变体。每个应用都在各自的环境中运行。请给我这两个应用的 URL。

变量替换

脚本同时支持环境变量替换和脚本参数替换：

1. 环境变量：${env://VAR} 和 ${env://VAR:-default} —— 优先处理
2. 脚本参数：${variable} 和 ${variable:-default} —— 在环境变量之后处理

变量可以通过命令行参数提供：

# 带有变量的脚本
mcphost script myscript.sh --args:directory /tmp --args:name "John"

变量语法

MCPHost 支持以下变量语法：

1. 必需的环境变量：${env://VAR} —— 必须在环境中设置
2. 可选的环境变量：${env://VAR:-default} —— 如果未设置则使用默认值
3. 必需的脚本参数：${variable} —— 必须通过 --args:variable value 提供
4. 可选的脚本参数：${variable:-default} —— 如果未提供则使用默认值

示例脚本，混合了环境变量和脚本参数：

#!/usr/bin/env -S mcphost script
---
mcpServers:
  github:
    type: "local"
    command: ["gh", "api"]
    environment:
      GITHUB_TOKEN: "${env://GITHUB_TOKEN}"
      DEBUG: "${env://DEBUG:-false}"
  
  filesystem:
    type: "local"
    command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "${env://WORK_DIR:-/tmp}"]

model: "${env://MODEL:-anthropic/claude-sonnet-4-5-20250929}"
---
你好 ${name:-World}！请列出 ${repo_type:-public} 用户 ${username} 的仓库。工作目录是 ${env://WORK_DIR:-/tmp}。使用 ${command:-gh} 命令获取 ${count:-10} 个仓库。

使用示例

# 先设置环境变量
export GITHUB_TOKEN="ghp_your_token_here"
export DEBUG="true"
export WORK_DIR="/home/user/projects"

# 使用环境变量和默认值：name="World"，repo_type="public"，command="gh"，count="10"
mcphost script myscript.sh

# 覆盖特定脚本参数
mcphost script myscript.sh --args:name "John" --args:username "alice"

# 覆盖多个脚本参数
mcphost script myscript.sh --args:name "John" --args:username "alice" --args:repo_type "private"

# 环境变量、提供的参数与默认值的混合
mcphost script myscript.sh --args:name "Alice" --args:command "gh api" --args:count "5"

默认值特性

• 空默认值: ${var:-} - 如果未提供则使用空字符串
• 复杂默认值: ${path:-/tmp/default/path} - 支持路径、URL等
• 默认值中的空格: ${msg:-Hello World} - 支持默认值中包含空格
• 向后兼容性: 现有的${variable}语法仍可正常使用，无需更改

重要提示:

• 无默认值的环境变量（如${env://GITHUB_TOKEN}）为必填项，必须在环境中设置。
• 无默认值的脚本参数（如${username}）为必填项，必须通过--args:variable value语法提供。
• 有默认值的变量为可选，若未提供则使用默认值。
• 环境变量会优先处理，随后才是脚本参数。

脚本特性

• 可执行性: 使用 shebang 行可直接执行（#!/usr/bin/env -S mcphost script）
• YAML 配置: 可在脚本中直接定义 MCP 服务器
• 嵌入式提示: 提示信息可直接包含在 YAML 文件中
• 变量替换: 使用${variable}和${variable:-default}语法，并配合--args:variable value
• 变量验证: 缺少必填变量时，脚本将退出并显示有用的错误信息。
• 交互模式: 若提示为空，则进入交互模式（适用于设置脚本）
• 配置回退: 若未定义mcpServers，则使用默认配置。
• 工具过滤: 支持按服务器设置allowedTools/excludedTools
• 干净退出: 完成后自动退出

注意: Shebang 行需要使用env -S来处理多单词命令mcphost script。这在大多数现代类 Unix 系统上都支持。

脚本示例

请参阅examples/scripts/目录下的示例脚本：

• example-script.sh - 自定义 MCP 服务器的脚本
• simple-script.sh - 使用默认配置回退的脚本

钩子系统

MCPHost 支持强大的钩子系统，允许您在执行过程中的特定点执行自定义命令。这使得安全策略、日志记录、自定义集成以及自动化工作流成为可能。

快速入门

1. 初始化钩子配置：

   mcphost hooks init
   

2. 查看当前生效的钩子：

   mcphost hooks list
   

3. 验证您的配置：

   mcphost hooks validate
   

配置

钩子通过 YAML 文件进行配置，优先级从高到低如下：

• .mcphost/hooks.yml（项目专用钩子）
• $XDG_CONFIG_HOME/mcphost/hooks.yml（用户全局钩子，默认为~/.config/mcphost/hooks.yml）

示例配置：

hooks:
  PreToolUse:
    - matcher: "bash"
      hooks:
        - type: command
          command: "/usr/local/bin/validate-bash.py"
          timeout: 5
  
  UserPromptSubmit:
    - hooks:
        - type: command
          command: "~/.mcphost/hooks/log-prompt.sh"

可用钩子事件

• PreToolUse: 在任何工具执行之前（bash、fetch、todo、MCP 工具）
• PostToolUse: 工具执行完成后
• UserPromptSubmit: 用户提交提示时
• Stop: 代理完成响应时
• SubagentStop: 子代理（Task 工具）完成时
• Notification: 当 MCPHost 发送通知时

安全性

⚠️ 警告: 钩子会在您的系统上执行任意命令。请仅使用来自可信来源的钩子，并在启用前始终检查钩子命令。

要临时禁用所有钩子，请使用--no-hooks标志：

mcphost --no-hooks

请参阅examples/hooks/目录下的示例钩子脚本：

• bash-validator.py - 验证并阻止危险的 bash 命令
• prompt-logger.sh - 记录所有用户提示及时间戳
• mcp-monitor.py - 监控并执行关于 MCP 工具使用的政策

非交互模式

运行单个提示并退出——非常适合脚本编写和自动化：

# 基本非交互式用法
mcphost -p "今天天气怎么样？"

# 静默模式——仅输出 AI 回答，不显示 UI 元素
mcphost -p "2+2等于多少？" --quiet

# 使用不同模型
mcphost -m ollama/qwen2.5:3b -p "解释量子计算" --quiet

模型生成参数

MCPHost 支持通过多种参数微调模型行为：

# 控制回答长度
mcphost -p "解释人工智能" --max-tokens 1000

# 调整创造力（0.0 = 专注，1.0 = 创意）
mcphost -p "写一个故事" --temperature 0.9

# 使用核采样控制多样性
mcphost -p "生成创意" --top-p 0.8

# 限制候选词数量以获得更聚焦的回答
mcphost -p "精确作答" --top-k 20

# 设置自定义停止序列
mcphost -p "生成代码" --stop-sequences "```","END"

这些参数适用于所有受支持的提供商（OpenAI、Anthropic、Google、Ollama），前提是底层模型支持。

可用模型

可通过--model（-m）选项指定模型：

• Anthropic Claude（默认）：anthropic/claude-sonnet-4-5-20250929、anthropic/claude-3-5-sonnet-latest、anthropic/claude-3-5-haiku-latest
• OpenAI: openai/gpt-4、openai/gpt-4-turbo、openai/gpt-3.5-turbo
• Google Gemini: google/gemini-2.0-flash、google/gemini-1.5-pro
• Ollama 模型: ollama/llama3.2、ollama/qwen2.5:3b、ollama/mistral
• OpenAI 兼容模型: 通过自定义端点和--provider-url指定的任何模型

示例

交互模式

# 使用 Ollama 的 Qwen 模型
mcphost -m ollama/qwen2.5:3b

# 使用 OpenAI 的 GPT-4
mcphost -m openai/gpt-4

# 使用 OpenAI 兼容模型，自定义 URL 和 API 密钥
mcphost --model openai/<your-model-name> \
--provider-url <your-base-url> \
--provider-api-key <your-api-key>

非交互模式

# 单一提示，完整 UI
mcphost -p "列出当前目录下的文件"

# 简洁模式，输出更干净，无花哨样式
mcphost -p "列出当前目录下的文件" --compact

# 静默模式，适合脚本编写（仅输出 AI 回答，无 UI 元素）
mcphost -p "法国的首都是哪里？" --quiet

# 在 shell 脚本中使用
RESULT=$(mcphost -p "计算 15 * 23" --quiet)
echo "答案是: $RESULT"

# 与其他命令管道连接
mcphost -p "生成一个随机 UUID" --quiet | tr '[:lower:]' '[:upper:]'

标志

• --provider-url string: 提供商 API 的基础 URL（适用于 OpenAI、Anthropic、Ollama 和 Google）
• --provider-api-key string: 提供商的 API 密钥（适用于 OpenAI、Anthropic 和 Google）
• --tls-skip-verify: 跳过 TLS 证书验证（警告：不安全，仅用于自签名证书）
• --config string: 配置文件位置（默认为 $HOME/.mcphost.yml）
• --system-prompt string: 系统提示文件位置
• --debug: 启用调试日志
• --max-steps int: 代理的最大步骤数（0 表示无限制，默认：0）
• -m, --model string: 要使用的模型（格式：提供商/模型）（默认为 "anthropic/claude-sonnet-4-5-20250929"）
• -p, --prompt string: 以非交互模式运行，并使用给定的提示
• --quiet: 抑制所有输出，仅保留 AI 响应（仅与 --prompt 一起使用）
• --compact: 启用简洁输出模式，不带花哨的样式（非常适合脚本和自动化）
• --stream: 启用流式响应（默认：true，使用 --stream=false 可禁用）

身份验证子命令

• mcphost auth login anthropic: 使用 OAuth 认证 Anthropic（替代 API 密钥）
• mcphost auth logout anthropic: 删除存储的 OAuth 凭据
• mcphost auth status: 显示身份验证状态

注意：OAuth 凭据（如果存在）优先于环境变量和 --provider-api-key 标志中的 API 密钥。

模型生成参数

• --max-tokens int: 响应中最大令牌数（默认：4096）
• --temperature float32: 控制响应的随机性（0.0-1.0，默认：0.7）
• --top-p float32: 通过核采样控制多样性（0.0-1.0，默认：0.95）
• --top-k int32: 通过限制从前 K 个令牌中采样来控制多样性（默认：40）
• --stop-sequences strings: 自定义停止序列（逗号分隔）

配置文件支持

所有命令行标志都可以通过配置文件进行配置。MCPHost 将按以下顺序查找配置：

1. ~/.mcphost.yml 或 ~/.mcphost.json（首选）
2. ~/.mcp.yml 或 ~/.mcp.json（向后兼容）

配置文件示例（~/.mcphost.yml）：

# MCP 服务器 - 新简化格式
mcpServers:
  filesystem-local:
    type: "local"
    command: ["npx", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    environment:
      DEBUG: "true"
  filesystem-builtin:
    type: "builtin"
    name: "fs"
    options:
      allowed_directories: ["/tmp", "/home/user/documents"]
  websearch:
    type: "remote"
    url: "https://api.example.com/mcp"

# 应用程序设置
model: "anthropic/claude-sonnet-4-5-20250929"
max-steps: 20
debug: false
system-prompt: "/path/to/system-prompt.txt"

# 模型生成参数
max-tokens: 4096
temperature: 0.7
top-p: 0.95
top-k: 40
stop-sequences: ["Human:", "Assistant:"]

# 流式配置
stream: false  # 禁用流式传输（默认：true）

# API 配置
provider-api-key: "your-api-key"      # 对于 OpenAI、Anthropic 或 Google
provider-url: "https://api.openai.com/v1"  # 自定义基础 URL
tls-skip-verify: false  # 跳过 TLS 证书验证（默认：false）

注意：命令行标志优先于配置文件中的值。

交互式命令

聊天时，您可以使用：

• /help: 显示可用命令
• /tools: 列出所有可用工具
• /servers: 列出已配置的 MCP 服务器
• /history: 显示对话历史
• /quit: 退出应用程序
• Ctrl+C: 随时退出

认证命令

可选的 Anthropic OAuth 认证（替代 API 密钥）：

• mcphost auth login anthropic: 使用 OAuth 进行认证
• mcphost auth logout anthropic: 删除存储的 OAuth 凭据
• mcphost auth status: 显示身份验证状态。

全局标志

• --config: 指定自定义配置文件位置

自动化与脚本 🤖

MCPHost 的非交互模式使其非常适合自动化、脚本编写以及与其他工具的集成。

使用场景

Shell 脚本

#!/bin/bash
# 获取天气并保存到文件
mcphost -p "纽约的天气如何？" --quiet > weather.txt

# 使用 AI 处理文件
for file in *.txt; do
    summary=$(mcphost -p "请总结此文件内容：$(cat $file)" --quiet)
    echo "$file: $summary" >> summaries.txt
done

CI/CD 集成

# 代码审查自动化
DIFF=$(git diff HEAD~1)
mcphost -p "请审查这段代码差异并提出改进建议：$DIFF" --quiet

# 生成发布说明
COMMITS=$(git log --oneline HEAD~10..HEAD)
mcphost -p "请根据这些提交记录生成发布说明：$COMMITS" --quiet

数据处理

# 处理 CSV 数据
mcphost -p "请分析这份 CSV 数据并提供见解：$(cat data.csv)" --quiet

# 生成报告
mcphost -p "请根据这份 JSON 数据创建摘要报告：$(cat metrics.json)" --quiet

API 集成

# 作为微服务使用
curl -X POST http://localhost:8080/process \
  -d "$(mcphost -p '生成一个 UUID' --quiet)"

脚本编写技巧

• 使用 --quiet 标志获取适合解析的干净输出（仅 AI 响应，无 UI）
• 使用 --compact 标志获得简化输出，去除花哨的样式（当您希望看到 UI 元素时）
• 注意：--compact 和 --quiet 互斥——使用 --quiet 时，--compact 无效
• 对于敏感数据，如 API 密钥，使用环境变量代替硬编码
• 在配置文件和脚本中使用 ${env://VAR} 语法进行环境变量替换
• 结合标准 Unix 工具（grep、awk、sed 等）
• 为长时间运行的操作设置适当的超时时间
• 在脚本中妥善处理错误
• 生产环境中使用环境变量存储 API 密钥

环境变量最佳实践

# 在环境中设置敏感变量
export GITHUB_TOKEN="ghp_your_token_here"
export OPENAI_API_KEY="your_openai_key"
export DATABASE_URL="postgresql://user:pass@localhost/db"

# 在配置文件中使用
mcpServers:
  github:
    environment:
      GITHUB_TOKEN: "${env://GITHUB_TOKEN}"
      DEBUG: "${env://DEBUG:-false}"

# 在脚本中使用
mcphost script my-script.sh --args:username alice

MCP 服务器兼容性 🔌

MCPHost 可以与任何符合 MCP 标准的服务器配合使用。有关示例和参考实现，请参阅 MCP 服务器仓库。

贡献 🤝

欢迎贡献！您可以：

• 通过问题提交 bug 报告或功能请求
• 创建拉取请求以改进功能
• 分享您自定义的 MCP 服务器
• 改进文档

请确保您的贡献遵循良好的编码实践，并包含适当的测试。

许可证 📄

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

致谢 🙏

• 感谢 Anthropic 团队提供的 Claude 模型和 MCP 规范
• 感谢 Ollama 团队提供的本地大模型运行时
• 感谢所有帮助改进这款工具的贡献者

MCPHost 快速上手指南

MCPHost 是一个命令行宿主应用，基于模型上下文协议（MCP），让大语言模型（LLM）能够安全地调用外部工具。它支持 Claude、OpenAI、Google Gemini 以及 Ollama 等主流模型。

环境准备

在开始之前，请确保满足以下系统要求和依赖：

• 操作系统：Linux, macOS 或 Windows
• Go 语言环境：需安装 Go 1.23 或更高版本
• 模型访问凭证（根据选择的模型准备其一）：
  • OpenAI: OPENAI_API_KEY
  • Anthropic (Claude): ANTHROPIC_API_KEY
  • Google (Gemini): GOOGLE_API_KEY
  • Ollama: 本地安装 Ollama 并拉取支持函数调用的模型（如 mistral）
• MCP 服务端：至少一个兼容 MCP 协议的工具服务器（MCPHost 内置了文件系统、Bash、Todo 和 HTTP 等基础服务器，也可连接远程或本地自定义服务器）。

环境变量配置示例

在终端中设置你的 API Key（以 OpenAI 为例）：

export OPENAI_API_KEY='your-openai-key'
# Anthropic
export ANTHROPIC_API_KEY='your-anthropic-key'
# Google
export GOOGLE_API_KEY='your-google-key'

若使用 Ollama，请确保服务正在运行：

ollama serve

安装步骤

推荐使用 Go 官方包管理器进行安装：

go install github.com/mark3labs/mcphost@latest

安装完成后，确保 $GOPATH/bin 已添加到你的系统 PATH 环境变量中，以便在任何目录下执行 mcphost 命令。

提示：国内开发者若遇到网络问题，可配置 GOPROXY 加速下载：

export GOPROXY=https://goproxy.cn,direct
go install github.com/mark3labs/mcphost@latest

基本使用

1. 交互式对话（默认模式）

直接运行命令即可进入交互模式。MCPHost 会自动加载内置的基础工具服务器（如文件系统操作、Bash 执行等），你可以直接与大模型对话并让它调用工具。

mcphost

启动后，你可以输入类似以下的指令：

"列出当前目录下的文件，并读取 README.md 的内容。"

2. 指定模型与提供商

默认情况下，它会尝试检测环境变量中的 API Key 来选择模型。你也可以通过参数显式指定：

# 使用 OpenAI GPT-4
mcphost --model openai/gpt-4

# 使用本地 Ollama 模型
mcphost --model ollama/mistral --provider-url http://localhost:11434

# 跳过 TLS 验证（仅用于本地自签名证书开发环境）
mcphost --provider-url https://192.168.1.100:443 --tls-skip-verify

3. 非交互式脚本模式

你可以将提示词作为参数传入，用于自动化脚本或管道操作：

echo "计算 25 乘以 4 的结果" | mcphost --non-interactive

或者直接使用 -p 标志：

mcphost -p "查看当前系统的内存使用情况" --non-interactive

4. 配置文件进阶（可选）

MCPHost 会在用户主目录自动生成配置文件（~/.mcphost.yml 或 ~/.mcphost.json）。你可以编辑该文件来配置自定义的 MCP 服务器。

示例：配置一个本地文件系统 MCP 服务器

创建或编辑 ~/.mcphost.yml：

mcpServers:
  filesystem:
    type: builtin
    name: fs
    options:
      allowed_directories: ["/tmp", "${env://HOME}/documents"]
    allowedTools: ["read_file", "write_file", "list_directory"]

model: "anthropic/claude-sonnet-4-5-20250929"
provider-api-key: "${env://ANTHROPIC_API_KEY}"

配置完成后，再次运行 mcphost 即可生效。支持使用 ${env://VAR} 语法在配置文件中引用环境变量，保障密钥安全。