personal-mcp

一个面向本地使用的 TypeScript MCP 网关，在统一控制台中管理 SSH、Prometheus 和 MySQL 工具。

Node.js TypeScript MCP License: MIT

快速开始 · 可用 MCP · 客户端接入 · 安全说明

personal-mcp 将多个 MCP 插件挂载到同一个仅监听 loopback 的 HTTP 服务，并提供响应式 Web 控制台、运行时配置热重载、健康检查和请求日志。每个插件也可以作为独立服务运行。

WARNING

当前服务没有身份认证，只允许监听127.0.0.1。请勿将端口直接暴露到局域网或公网。

功能亮点

统一网关：通过一套服务暴露多个 Streamable HTTP MCP endpoint。
可视化配置：在 Web 控制台中管理插件配置，无需重启 Node.js 进程。
独立运行：SSH、Prometheus 和 MySQL MCP 均可单独启动。
安全默认值：限制 loopback 监听；SSH 强制白名单和 host key 校验；敏感运行时配置不进入 Git。
可观测性：提供状态、健康检查及带 request_id 的结构化请求日志。

可用 MCP

MCP	能力	网关 endpoint	详细文档
SSH	获取只读系统快照；经双重确认后执行远程命令	`/ssh/mcp`	SSH MCP
Prometheus	执行 PromQL 即时查询和区间查询	`/prometheus/mcp`	Prometheus MCP
MySQL	执行 SQL；列出并读取表数据资源	`/mysql/mcp`	MySQL MCP

工作方式

flowchart LR
    Clients[Codex / Claude Code / MCP Inspector] --> Gateway[personal-mcp gateway]
    Browser[Web 控制台] --> Gateway
    Gateway --> SSH[SSH MCP]
    Gateway --> Prom[Prometheus MCP]
    Gateway --> MySQL[MySQL MCP]
    SSH --> Hosts[白名单主机]
    Prom --> Metrics[Prometheus]
    MySQL --> Database[MySQL]

快速开始

环境要求

Node.js 20 或更高版本
npm
至少一个需要接入的目标服务：SSH 主机、Prometheus 或 MySQL

安装并启动

git clone https://github.com/luozijian1990/personal-mcp.git
cd personal-mcp
npm ci
npm run dev

打开 http://127.0.0.1:3100/。网关可以在尚未配置插件时启动；进入对应 MCP 的详情页填写配置，然后点击“保存并重载 MCP”。

默认地址：

服务	地址
Web 控制台	http://127.0.0.1:3100/
服务状态	http://127.0.0.1:3100/api/status
健康检查	http://127.0.0.1:3100/health
SSH MCP	http://127.0.0.1:3100/ssh/mcp
Prometheus MCP	http://127.0.0.1:3100/prometheus/mcp
MySQL MCP	http://127.0.0.1:3100/mysql/mcp

配置

推荐通过 Web 控制台完成首次配置。也可以复制脱敏模板，或在首次启动时传入环境变量：

cp .runtime-config.example.json .runtime-config.json

插件	主要环境变量
SSH	`SSH_MCP_ALLOWED_TARGETS`、`SSH_MCP_USERNAME`、`SSH_MCP_PORTS`、`SSH_MCP_PRIVATE_KEY_PATH`、`SSH_MCP_KNOWN_HOSTS_PATH`
Prometheus	`PROMETHEUS_MCP_URL`、`PROMETHEUS_MCP_QUERY_TIMEOUT`
MySQL	`MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_USER`、`MYSQL_PASSWORD`、`MYSQL_DATABASE`

控制台保存的值写入 .runtime-config.json，后续启动时优先于同名环境变量。该文件以 0600 权限写入并已被 .gitignore 排除。可通过 MCP_RUNTIME_CONFIG_PATH 更改保存位置。

TIP

各字段含义、完整示例和插件特有约束，请查看上方表格中的独立文档。

客户端接入

网关启动后，可将任意 endpoint 添加到 MCP 客户端：

# Codex
codex mcp add ssh --url http://127.0.0.1:3100/ssh/mcp
codex mcp add prometheus --url http://127.0.0.1:3100/prometheus/mcp
codex mcp add mysql --url http://127.0.0.1:3100/mysql/mcp

# Claude Code
claude mcp add --transport http ssh http://127.0.0.1:3100/ssh/mcp
claude mcp add --transport http prometheus http://127.0.0.1:3100/prometheus/mcp
claude mcp add --transport http mysql http://127.0.0.1:3100/mysql/mcp

也可以使用 MCP Inspector 调试 endpoint：

npx @modelcontextprotocol/inspector http://127.0.0.1:3100/ssh/mcp

独立运行插件

MCP	开发模式	构建后运行	默认端口
SSH	`npm run dev:ssh`	`npm run start:ssh`	`3101`
Prometheus	`npm run dev:prometheus`	`npm run start:prometheus`	`3102`
MySQL	`npm run dev:mysql`	`npm run start:mysql`	`3103`

通过 PORT 环境变量可以覆盖默认端口。生产模式运行前需要先执行 npm run build。

安全说明

SSH 仅允许访问显式配置的目标，不传递密码、不关闭 host key 检查，也不会自动接受未知指纹。
ssh_execute_command 默认关闭；启用后，客户端仍需传入 acknowledgeRemoteChangeRisk: true。
MySQL 的 execute_sql 可以修改数据，请使用权限最小化的专用数据库账号。
服务会记录 MCP 请求和响应，SQL、命令或查询结果可能出现在 logs/mcp.log 中，请按敏感数据管理该文件。
.runtime-config.json、日志、构建产物和本地 SSH identity 文件均不会被 Git 跟踪。

开发

# 构建前端和服务端，并运行测试
npm run check

# 仅构建
npm run build

# 运行构建产物
npm start

项目主要目录：

src/
├── apps/       # 网关与独立服务入口
├── core/       # HTTP、插件注册、日志和运行时配置
├── plugins/    # SSH、Prometheus、MySQL 插件
└── ui/         # React Web 控制台

personal-mcp

personal-mcp

功能亮点

可用 MCP

工作方式

快速开始

环境要求

安装并启动

配置

客户端接入

独立运行插件

安全说明

开发

Latest Blog Posts

MCP directory API