使用说明

英语 | 日语

🏮 Hatago MCP 集线中心

Hatago（旅籠）——连接现代AI工具与MCP服务器的中继点。

概述

Hatago MCP Hub 是一个轻量级的中心，它统一了来自 Claude Code、Codex CLI、Cursor、Windsurf 和 VS Code 等工具对多个 MCP（模型上下文协议）服务器的访问。

文档

文档索引： docs/README.md
Canonical CLI & Hub 指南： packages/mcp-hub/README.md
公共文档网站（日文默认）：https://hatago.dev/ja/ — 英文：https://hatago.dev/en/

Dev.to：使用 Hatago MCP Hub 开始多 MCP（Mod 加载器）之旅——一个配置连接全部

✨ 特点/功能

🚀 性能（v0.0.14）

启动速度提升8.44倍 - 85.66毫秒 → 10.14毫秒
17% 更小的包装 - 1.04MB → 854KB
简化架构 - 直接服务器管理，无需抽象层

🎯 简单且轻量

零配置启动（HTTP模式） - npx @himorishige/hatago-mcp-hub serve --http
对现有项目无侵入性 - 不会污染你的项目目录

🔌 丰富的连接性

多交通方式支持 - 标准输入输出（STDIO）/ 超文本传输协议（HTTP）/ 服务器发送事件（SSE）
远程MCP代理 - 与基于HTTP的MCP服务器进行透明连接
NPX服务器集成 - npm包MCP服务器的动态管理

🏮 额外功能

配置更新

需要手动重启 - 配置更改需要重启服务器
替代方案：
- 使用进程管理器（PM2、nodemon）进行自动重启
- 示例： nodemon --exec "hatago serve --http" --watch hatago.config.json
- 或者使用PM2： pm2 start "hatago serve" --watch hatago.config.json
动态工具列表更新 - 支持 notifications/tools/list_changed 通知

进度通知转发

子服务器通知转发 - 透明转发 notifications/progress
长期运行操作支持 - 实时进度更新
本地/远程支持 - 与多种MCP服务器类型兼容

内置内部资源

hatago://servers - 当前连接服务器的JSON快照（ID、状态、类型、工具、资源、提示）

增强功能

环境变量展开 - 兼容Claude编码 ${VAR} 和 ${VAR:-default} 语法
配置验证 - 使用Zod模式实现类型安全的配置
基于标签的服务器过滤 - 使用标签对服务器进行分组和过滤
配置继承 - 通过（某种方式）扩展基础配置 extends “field for DRY principle”的中文翻译是：“遵循DRY原则的字段”。这里，“DRY”原则是指“Don't Repeat Yourself”（不要重复自己），是编程中的一种设计原则，旨在提高代码的可维护性和可读性

最小化集线器接口（IHub）

外部包（server/test-utils）使用了一个轻量级的（或“简化的”） IHub 通过接口来避免与具体类的紧密耦合。

import type { IHub } from '@himorishige/hatago-hub';
import { createHub } from '@himorishige/hatago-hub/node';

const hub: IHub = createHub({
  preloadedConfig: { data: { version: 1, mcpServers: {} } }
}) as IHub;
await hub.start();
hub.on('tool:called', (evt) => {
  /* metrics, logs */
});
await hub.stop();

提取的用于薄型轮毂的模块：

RPC 处理程序： packages/hub/src/rpc/handlers.ts
HTTP 处理程序： packages/hub/src/http/handler.ts

📁 项目结构

packages/
├── mcp-hub/        # Main npm package (@himorishige/hatago-mcp-hub)
├── server/         # Server implementation (@himorishige/hatago-server)
├── hub/            # Hub core (@himorishige/hatago-hub)
├── core/           # Shared types (@himorishige/hatago-core)
├── runtime/        # Runtime components (@himorishige/hatago-runtime)
├── transport/      # Transport layer (@himorishige/hatago-transport)
├── cli/            # CLI tools (@himorishige/hatago-cli)
├── hub-management/ # Management components (@himorishige/hatago-hub-management)
└── test-fixtures/  # Test utilities

📦 安装

快速入门（无需安装）

# Initialize configuration
npx @himorishige/hatago-mcp-hub init

# Start in STDIO mode (for Claude Code)
# NOTE: STDIO requires a config file path
npx @himorishige/hatago-mcp-hub serve --stdio --config ./hatago.config.json

# Or start in HTTP mode without a config (demo/dev)
npx @himorishige/hatago-mcp-hub serve --http

全球部署

# Install globally
npm install -g @himorishige/hatago-mcp-hub

# Use with hatago command
hatago init
hatago serve

作为项目依赖

# Install as dependency
npm install @himorishige/hatago-mcp-hub

# Add to package.json scripts
{
  "scripts": {
    "mcp": "hatago serve"
  }
}

🚀 使用方法

克劳德代码，Codex CLI，Gemini CLI

STDIO 模式（推荐）

克劳德代码 / 双子座命令行界面

添加到 .mcp.json：

{
  "mcpServers": {
    "hatago": {
      "command": "npx",
      "args": [
        "@himorishige/hatago-mcp-hub",
        "serve",
        "--stdio",
        "--config",
        "./hatago.config.json"
      ]
    }
  }
}

Codex CLI（命令行界面）

添加到 ~/.codex/config.toml：

[mcp_servers.hatago]
command = "npx"
args = ["-y", "@himorishige/hatago-mcp-hub", "serve", "--stdio", "--config", "./hatago.config.json"]

HTTP 模式

Claude Code / Gemini CLI（注：这里的“Code”可能指的是某种代码或编程环境，但结合上下文，“Claude Code”可能是一个特定项目或工具的名称，因此直接保留原样；“Gemini CLI”则是指Gemini的命令行界面）

添加到 .mcp.json:

{
  "mcpServers": {
    "hatago": {
      "url": "http://localhost:3535/mcp"
    }
  }
}

Codex CLI（命令行界面）

添加到 ~/.codex/config.toml：

[mcp_servers.hatago]
command = "npx"
args = ["-y", "mcp-remote", "http://localhost:3535/mcp"]

MCP 检测器（或 MCP 检查器）

用于测试和调试：

# Start in HTTP mode
hatago serve --http --port 3535

# Connect with MCP Inspector
# Endpoint: http://localhost:3535/mcp

访问 MCP 检查员

指标（可选加入）

启用轻量级内存指标并暴露一个HTTP端点：

HATAGO_METRICS=1 hatago serve --http --port 3535
# Then visit: http://localhost:3535/metrics

注：

默认情况下，指标功能是禁用的，且在关闭时几乎不会产生任何开销。
当……时，JSON日志可用 HATAGO_LOG=json （尊敬地 HATAGO_LOG_LEVEL）。

⚙️ 配置

基本配置

创造 hatago.config.json:

{
  "$schema": "https://raw.githubusercontent.com/himorishige/hatago-mcp-hub/main/schemas/config.schema.json",
  "version": 1,
  "logLevel": "info",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

远程服务器配置

{
  "mcpServers": {
    "deepwiki": {
      "url": "https://mcp.deepwiki.com/sse",
      "type": "sse"
    },
    "custom-api": {
      "url": "https://api.example.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

配置策略

策略1：基于标签的过滤

在单个配置文件中按标签分组服务器：

{
  "mcpServers": {
    "filesystem-dev": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "tags": ["dev", "local"]
    },
    "github-prod": {
      "url": "https://api.github.com/mcp",
      "type": "http",
      "tags": ["production", "github"]
    },
    "database": {
      "command": "mcp-server-postgres",
      "tags": ["dev", "production", "database"]
    }
  }
}

从特定标签开始：

# Only start servers tagged as "dev"
hatago serve --tags dev

# Start servers with either "dev" or "test" tags
hatago serve --tags dev,test

# Japanese tags are supported
hatago serve --tags 開発,テスト

策略2：配置继承

根据环境拆分配置 extends 字段：

基本配置 (~/.hatago/base.config.json):

{
  "version": 1,
  "logLevel": "info",
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

工作配置 （./work.config.json):

{
  "extends": "~/.hatago/base.config.json",
  "logLevel": "debug",
  "mcpServers": {
    "github": {
      "env": {
        "GITHUB_TOKEN": "${WORK_GITHUB_TOKEN}",
        "DEBUG": null
      }
    },
    "internal-tools": {
      "url": "https://internal.company.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_TOKEN}"
      }
    }
  }
}

特点：

继承子配置覆盖父配置值
多个父母： "extends": ["./base1.json", "./base2.json"]
路径解析支持 ~相对路径和绝对路径
环境删除使用 null 移除继承的环境变量

选择策略

策略	基于标签的	基于继承的
文件	单配置	多配置
开关	`--tags` 选项	`--config` 选项
管理	集中式	分布式
最适合于	团队共享，简单设置	复杂环境，个性化定制

环境变量扩展

支持Claude代码兼容语法：

${VAR} - 扩展为VAR的值（若未定义则报错）
${VAR:-default} - 如果 VAR 未定义，则使用默认值

📋 命令

`hatago init`

通过交互式设置创建配置文件：

hatago init                    # Interactive mode
hatago init --mode stdio       # STDIO mode config
hatago init --mode http        # HTTP mode config
hatago init --force            # Overwrite existing

`hatago serve`

启动MCP Hub服务器：

hatago serve --stdio --config ./hatago.config.json  # STDIO mode (default, requires config)
hatago serve --http                                     # HTTP mode (config optional)
hatago serve --config custom.json  # Custom config
hatago serve --verbose         # Debug logging
hatago serve --tags dev,test   # Filter servers by tags
hatago serve --env-file ./.env # Load variables from .env before start (repeatable)
hatago serve --env-override    # Override existing env vars when using --env-file

从文件加载环境变量

使用 --env-file <path...> 在配置解析之前加载变量。这有助于解决 ${VAR} 并且 ${VAR:-default} 在不将变量全局导出的情况下使用占位符。

格式： KEY=VALUE， export KEY=VALUE， # 注释，空行。
引号已移除；转义了支持字符 \n， \r， \t。
路径：相对于当前工作目录（CWD）， ~/ 扩展到家庭。
优先级：文件按给定顺序应用；已存在的 process.env 除非……否则密钥将被保留 --env-override 已提供。

✨ 性能提升（v0.0.14）

启动速度提升8.44倍85.66毫秒 → 10.14毫秒
**包装体积缩小了17%**1.04MB → 854KB（减少了181KB）
简化架构移除了增强型集线器和管理层
权衡取舍内置的配置监视功能已移除（请改用 nodemon/PM2 代替）

🔧 高级用法

程序化API

import { startServer } from '@himorishige/hatago-mcp-hub';

// Start server programmatically
await startServer({
  mode: 'stdio',
  config: './hatago.config.json',
  logLevel: 'info'
});

创建自定义中心（或集线器）

import { createHub } from '@himorishige/hatago-mcp-hub';

const hub = createHub({
  mcpServers: {
    memory: {
      command: 'npx',
      args: ['@modelcontextprotocol/server-memory']
    }
  }
});

// Use hub directly in your application
const tools = await hub.listTools();

🏗️ 建筑学

Client (Claude Code, etc.)
    ↓
Hatago Hub (Router + Registry)
    ↓
MCP Servers (Local, NPX, Remote)

支持的MCP服务器

本地服务器

任何可执行的MCP服务器
Python、Node.js 或二进制服务器
使用MCP协议的自定义脚本

NPX 服务器

@modelcontextprotocol/server-filesystem
@modelcontextprotocol/server-github
@modelcontextprotocol/server-memory
任何通过npm发布的MCP服务器

远程服务器

DeepWiki MCP（https://mcp.deepwiki.com/sse)
任何基于HTTP的MCP终端节点
使用MCP协议的自定义API服务器

🐛 故障排除

常见问题

“未设置 onNotification 处理器”警告
- 在HTTP模式下使用StreamableHTTP传输时是正常的
- 集线器正确处理通知
服务器连接失败
- 验证环境变量是否已设置
- 检查远程服务器URL是否可访问
- 使用 --verbose 用于详细日志的标志
工具名称冲突
- Hatago 自动添加服务器ID前缀
- 原始名称在中心节点中保留

调试模式

# Enable verbose logging
hatago serve --verbose

# Check server status
hatago status

使用说明

🏮 Hatago MCP 集线中心

概述

文档

✨ 特点/功能

🚀 性能（v0.0.14）

🎯 简单且轻量

🔌 丰富的连接性

🏮 额外功能

配置更新

进度通知转发

内置内部资源

增强功能

最小化集线器接口（IHub）

📁 项目结构

📦 安装

快速入门（无需安装）

全球部署

作为项目依赖

🚀 使用方法

克劳德代码，Codex CLI，Gemini CLI

STDIO 模式（推荐）

克劳德代码 / 双子座命令行界面

Codex CLI（命令行界面）

HTTP 模式

Claude Code / Gemini CLI（注：这里的“Code”可能指的是某种代码或编程环境，但结合上下文，“Claude Code”可能是一个特定项目或工具的名称，因此直接保留原样；“Gemini CLI”则是指Gemini的命令行界面）

Codex CLI（命令行界面）

MCP 检测器（或 MCP 检查器）

指标（可选加入）

⚙️ 配置

基本配置

远程服务器配置

配置策略

策略1：基于标签的过滤

策略2：配置继承

选择策略

环境变量扩展

📋 命令

hatago init

hatago serve

从文件加载环境变量

✨ 性能提升（v0.0.14）

🔧 高级用法

程序化API

创建自定义中心（或集线器）

🏗️ 建筑学

支持的MCP服务器

本地服务器

NPX 服务器

远程服务器

🐛 故障排除

常见问题

调试模式

📚 文档

🤝 贡献（或“参与贡献”）

📄 许可证

🔗 链接

🙏 致谢

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器

`hatago init`

`hatago serve`