MCPHost 🤖

⚠️ MCPHost 已停止主动维护

MCPHost 已停止积极开发。 该项目的后继项目是 Kit，它基于 MCPHost 的基础，采用了更强大、更易扩展的架构。

👉 我们建议所有用户迁移到 Kit。

此代码仓库现已归档，后续不会再有更新或错误修复。

---

MCPHost 🤖

一款 CLI 主机应用，可通过模型上下文协议（MCP）让大模型（LLM）与外部工具交互。目前支持 Claude、OpenAI、Google Gemini 和 Ollama 模型。

在 Discord 上讨论此项目

目录

• 概览
• 功能
• 要求
• 环境设置
• 安装
• SDK 用法
• 配置
  • MCP 服务
  • 环境变量替换
  • 简化的配置架构
  • 工具筛选
  • 旧版配置支持
  • 传输类型
  • 系统提示词
• 用法
  • 交互模式
  • 脚本模式
  • 钩子系统
  • 非交互模式
  • 模型生成参数
  • 可用模型
  • 示例
  • 标志
  • 身份验证子命令
  • 配置文件支持
  • 交互式命令
• 自动化与脚本编写
• MCP 服务兼容性
• 贡献
• 许可证
• 致谢

概览 🌟

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

• 主机（如 MCPHost）是管理连接和交互的 LLM 应用
• 客户端与 MCP 服务保持 1:1 连接
• 服务端为 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 服务的位置和参数
• 不同模型类型采用一致的命令接口
• 可配置用于上下文管理的消息历史窗口
• 支持 Anthropic OAuth 身份验证（可替代 API 密钥）
• 钩子系统，用于自定义集成和安全策略
• 在配置和脚本中进行环境变量替换
• 内置常用功能的服务（filesystem、bash、todo、http）

要求 📋

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

环境设置 🔧

1. API 密钥：

# For all providers (use --provider-api-key flag or these environment variables)
export OPENAI_API_KEY='your-openai-key'        # For OpenAI
export ANTHROPIC_API_KEY='your-anthropic-key'  # For Anthropic
export GOOGLE_API_KEY='your-google-key'        # For 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）： 如果你的服务提供方使用自签名证书（例如使用 HTTPS 的本地 Ollama），可以跳过证书验证：

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()
    
    // Create MCPHost instance with default configuration
    host, err := sdk.New(ctx, nil)
    if err != nil {
        panic(err)
    }
    defer host.Close()
    
    // Send a prompt and get response
    response, err := host.Prompt(ctx, "What is 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}"  # Required - will fail if not set

用法：

# Set required environment variables
export GITHUB_TOKEN="ghp_your_token_here"
export OPENAI_API_KEY="your_openai_key"

# Optionally override defaults
export DEBUG="true"
export MODEL="openai/gpt-4"

# Run 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"
      ]
    }
  }
}

旧版 Streamable 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：使用 Streamable HTTP 协议连接到服务（用于 "remote" 服务）
• inprocess：以内置进程内方式运行服务，以获得最佳性能（用于 "builtin" 服务）

简化后的架构会自动映射：

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

系统提示词

你可以使用 --system-prompt 标志指定自定义系统提示词。你可以：

1. 直接以文本形式传入提示词：

   mcphost --system-prompt "You are a helpful assistant that responds in a friendly tone."
   

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

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

   assistant.md 文件示例：

   You are a helpful coding assistant. 
   
   Please:
   - Write clean, readable code
   - Include helpful comments
   - Follow best practices
   - Explain your reasoning
   

用法 🚀

MCPHost 是一个 CLI 工具，可让你通过统一接口与各种 AI 模型交互。它通过 MCP 服务支持各种工具，并可在交互模式和非交互模式下运行。

交互模式（默认）

启动交互式对话会话：

mcphost

脚本模式

运行支持变量替换的、基于 YAML 的可执行自动化脚本：

# Using the script subcommand
mcphost script myscript.sh

# With variables
mcphost script myscript.sh --args:directory /tmp --args:name "John"

# Direct execution (if executable and has shebang)
./myscript.sh

脚本格式

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

#!/usr/bin/env -S mcphost script
---
# This script uses the container-use MCP server from https://github.com/dagger/container-use
mcpServers:
  container-use:
    type: "local"
    command: ["cu", "stdio"]
prompt: |
  Create 2 variations of a simple hello world app using Flask and FastAPI. 
  Each in their own environment. Give me the URL of each app
---

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

#!/usr/bin/env -S mcphost script
---
# This script uses the container-use MCP server from https://github.com/dagger/container-use
mcpServers:
  container-use:
    type: "local"
    command: ["cu", "stdio"]
---
Create 2 variations of a simple hello world app using Flask and FastAPI. 
Each in their own environment. Give me the URL of each app

变量替换

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

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

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

# Script with variables
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}"
---
Hello ${name:-World}! Please list ${repo_type:-public} repositories for user ${username}.
Working directory is ${env://WORK_DIR:-/tmp}.
Use the ${command:-gh} command to fetch ${count:-10} repositories.

用法示例

# Set environment variables first
export GITHUB_TOKEN="ghp_your_token_here"
export DEBUG="true"
export WORK_DIR="/home/user/projects"

# Uses env vars and defaults: name="World", repo_type="public", command="gh", count="10"
mcphost script myscript.sh

# Override specific script arguments
mcphost script myscript.sh --args:name "John" --args:username "alice"

# Override multiple script arguments  
mcphost script myscript.sh --args:name "John" --args:username "alice" --args:repo_type "private"

# Mix of env vars, provided args, and default values
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：Agent 完成响应时
• SubagentStop：子 Agent（Task 工具）完成时
• Notification：MCPHost 发送通知时

安全

⚠️ 警告：Hook 会在你的系统上执行任意命令。请仅使用可信来源的 Hook，并在启用前务必检查 Hook 命令。

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

mcphost --no-hooks

请参阅 examples/hooks/ 中的 Hook 脚本示例：

• bash-validator.py - 验证并拦截危险的 bash 命令
• prompt-logger.sh - 记录所有用户提示词及其时间戳
• mcp-monitor.py - 监控并强制执行 MCP 工具使用策略

非交互模式

运行单条提示词并退出，非常适合脚本和自动化：

# Basic non-interactive usage
mcphost -p "What is the weather like today?"

# Quiet mode - only output the AI response (no UI elements)
mcphost -p "What is 2+2?" --quiet

# Use with different models
mcphost -m ollama/qwen2.5:3b -p "Explain quantum computing" --quiet

模型生成参数

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

# Control response length
mcphost -p "Explain AI" --max-tokens 1000

# Adjust creativity (0.0 = focused, 1.0 = creative)
mcphost -p "Write a story" --temperature 0.9

# Control diversity with nucleus sampling
mcphost -p "Generate ideas" --top-p 0.8

# Limit token choices for more focused responses
mcphost -p "Answer precisely" --top-k 20

# Set custom stop sequences
mcphost -p "Generate code" --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 使用自定义端点指定任意模型

示例

交互模式

# Use Ollama with Qwen model
mcphost -m ollama/qwen2.5:3b

# Use OpenAI's GPT-4
mcphost -m openai/gpt-4

# Use OpenAI-compatible model with custom URL and API key
mcphost --model openai/<your-model-name> \
--provider-url <your-base-url> \
--provider-api-key <your-api-key>

非交互模式

# Single prompt with full UI
mcphost -p "List files in the current directory"

# Compact mode for cleaner output without fancy styling
mcphost -p "List files in the current directory" --compact

# Quiet mode for scripting (only AI response output, no UI elements)
mcphost -p "What is the capital of France?" --quiet

# Use in shell scripts
RESULT=$(mcphost -p "Calculate 15 * 23" --quiet)
echo "The answer is: $RESULT"

# Pipe to other commands
mcphost -p "Generate a random 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：system-prompt 文件位置
• --debug：启用调试日志
• --max-steps int：Agent 步骤的最大数量（0 表示不限制，默认值：0）
• -m, --model string：要使用的模型（格式：provider/model）（默认值 "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：响应中的最大 token 数量（默认值：4096）
• --temperature float32：控制响应的随机性（0.0-1.0，默认值：0.7）
• --top-p float32：通过核采样控制多样性（0.0-1.0，默认值：0.95）
• --top-k int32：通过限制采样范围内排名靠前的 K 个 token 来控制多样性（默认值：40）
• --stop-sequences strings：自定义停止序列（以逗号分隔）

配置文件支持

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

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

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

# MCP Servers - New Simplified Format
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"

# Application settings
model: "anthropic/claude-sonnet-4-5-20250929"
max-steps: 20
debug: false
system-prompt: "/path/to/system-prompt.txt"

# Model generation parameters
max-tokens: 4096
temperature: 0.7
top-p: 0.95
top-k: 40
stop-sequences: ["Human:", "Assistant:"]

# Streaming configuration
stream: false  # Disable streaming (default: true)

# API Configuration
provider-api-key: "your-api-key"      # For OpenAI, Anthropic, or Google
provider-url: "https://api.openai.com/v1"  # Custom base URL
tls-skip-verify: false  # Skip TLS certificate verification (default: 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
# Get weather and save to file
mcphost -p "What's the weather in New York?" --quiet > weather.txt

# Process files with AI
for file in *.txt; do
    summary=$(mcphost -p "Summarize this file: $(cat $file)" --quiet)
    echo "$file: $summary" >> summaries.txt
done

CI/CD 集成

# Code review automation
DIFF=$(git diff HEAD~1)
mcphost -p "Review this code diff and suggest improvements: $DIFF" --quiet

# Generate release notes
COMMITS=$(git log --oneline HEAD~10..HEAD)
mcphost -p "Generate release notes from these commits: $COMMITS" --quiet

数据处理

# Process CSV data
mcphost -p "Analyze this CSV data and provide insights: $(cat data.csv)" --quiet

# Generate reports
mcphost -p "Create a summary report from this JSON: $(cat metrics.json)" --quiet

API 集成

# Use as a microservice
curl -X POST http://localhost:8080/process \
  -d "$(mcphost -p 'Generate a UUID' --quiet)"

脚本编写提示

• 使用 --quiet 标志获取便于解析的干净输出（仅包含 AI 响应，不含 UI）
• 使用 --compact 标志获取不含复杂样式的简化输出（适用于需要查看 UI 元素的情况）
• 注意：--compact 和 --quiet 不能同时使用；使用 --quiet 时，--compact 不起作用
• 对于 API 密钥等敏感数据，请使用环境变量，而不要将其硬编码
• 在配置文件和脚本中使用 ${env://VAR} 语法替换环境变量
• 与标准 Unix 工具（grep、awk、sed 等）结合使用
• 为长时间运行的操作设置合适的超时时间
• 在脚本中妥善处理错误
• 在生产环境中使用环境变量存储 API 密钥

环境变量最佳实践

# Set sensitive variables in environment
export GITHUB_TOKEN="ghp_your_token_here"
export OPENAI_API_KEY="your_openai_key"
export DATABASE_URL="postgresql://user:pass@localhost/db"

# Use in config files
mcpServers:
  github:
    environment:
      GITHUB_TOKEN: "${env://GITHUB_TOKEN}"
      DEBUG: "${env://DEBUG:-false}"

# Use in scripts
mcphost script my-script.sh --args:username alice

MCP 服务兼容性 🔌

MCPHost 可与任何兼容 MCP 的服务配合使用。如需查看示例和参考实现，请参阅 MCP 服务仓库。

参与贡献 🤝

欢迎参与贡献！你可以：

• 通过 issues 提交错误报告或功能请求
• 创建 pull request 改进项目
• 分享自定义 MCP 服务
• 改进文档

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

许可证 📄

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

致谢 🙏

• 感谢 Anthropic 团队打造 Claude 并制定 MCP 规范
• 感谢 Ollama 团队提供本地 LLM 运行时
• 感谢所有帮助改进此工具的贡献者