🔴 mcp脉冲
模型上下文协议（MCP）服务器的实时监控和可观察性仪表板。 全面了解您的AI工作流程——在漂亮的实时仪表板中跟踪工具调用、延迟、错误和使用模式。
______________________________________________________________________
*带有实时指标、呼叫跟踪和警报的实时仪表板*
______________________________________________________________________
✨ 特性
📊 实时仪表板
- 实时通话记录 --观察每次MCP工具调用
- 延迟跟踪 --每次呼叫、每台服务器和滚动平均直方图
- 错误率监控 --带有堆栈痕迹的表面故障工具
- 请求量 --通话/分钟，时间窗口可配置
🔍 深度可观察性
- 结构化日志记录 --每个请求/响应都有完整的JSON有效负载检查
- 工具使用排行榜 --知道你的人工智能最常调用哪些工具
- 会话重放 --从头到尾重播任何捕获的会话
- 筛选和搜索 --按服务器、工具名称、状态、延迟或时间范围
🚨 智能警报
- 阈值警报 --当错误率或延迟超过限制时通知
- 异常检测 --自动标记异常图案
- Webhook+log+CSV --灵活的警报传递
🧩 MCP生态系统整合
- 适用于任何SSE传输 --所有官方MCP服务器（文件系统、GitHub、Slack等）
- 零代码集成 --通行证
--mcp-pulse标记到任何兼容的服务器 - 协议感知 --理解
initialize,tools/list,tools/call,sampling/create,roots/list
💻 开发者体验
- WebSocket+HTTP --将仪表板连接到本地或远程服务器
- 默认情况下为暗模式 --OLED友好的深色主题
- 导出为CSV/JSON --完整的原始数据导出以供分析
- 健康检查端点 —
/health用于容器编排
______________________________________________________________________
⚡ 快速开始
1--安装
npm install -g mcp-pulse2--启动仪表板
mcp-pulse dashboard
# → Opens at http://localhost:30003--代理任何MCP服务器
在一个 新终端，代理任何基于SSE的MCP服务器：
# Wrap the official filesystem server
npx @modelcontextprotocol/server-filesystem ./projects \
--mcp-pulse \
--mcp-pulse-port 3100
# Or wrap via stdio with the pulse proxy
cat my_server_output.json | mcp-pulse proxy --protocol sse --port 31004--打开浏览器
http://localhost:3000______________________________________________________________________
🐳 码头工人
# Run dashboard
docker run -p 3000:3000 -p 3100:3100 \
--env MCP_PULSE_PORT=3100 \
SergiuPogor/mcp-pulse:latest
# Proxy an MCP server inside Docker
docker run -p 3100:3100 \
--env MCP_PULSE_TARGET=http://your-server:3001 \
SergiuPogor/mcp-pulse:latest proxy______________________________________________________________________
📐 建筑
┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐
│ MCP Client │──────│ MCP Server │──────│ mcp-pulse Proxy │
│ (Claude, │ SSE │ (official │──────│ (intercepts all │
│ Cursor, │ │ servers) │ │ JSON-RPC messages) │
│ etc.) │ │ │ │ │
└──────────────┘ └──────────────┘ └──────────┬───────────┘
│ HTTP/WS
▼
┌──────────────────┐
│ mcp-pulse │
│ Dashboard │
│ (Express + WS) │
└──────────────────┘代理如何工作
- 客户端启动与MCP服务器的SSE连接
mcp-pulse proxy拦截JSON-RPC流量- 每条消息都会被实时记录、计时和转发
- Dashboard通过WebSocket接收实时流
- 指标在内存中聚合，具有可配置的保留期
______________________________________________________________________
🛠️ CLI参考
mcp-pulse [command]
Commands:
dashboard Start the web dashboard (default port 3000)
proxy Start a proxy server that intercepts MCP traffic
proxy:stdio Wrap a stdio-based MCP server ( Pipes JSON-RPC)
alert Run the alert engine (reads from dashboard API)
export Export captured data to CSV or JSON
Options:
--port, -p Port for dashboard or proxy [default: 3000]
--target, -t Target MCP server URL (for proxy) [required]
--protocol Transport: sse | stdio | stream [default: sse]
--retention How many hours to keep data [default: 24]
--alert-threshold Error rate % to trigger alert [default: 10]
--json Output raw JSON (for scripting)
--verbose Enable verbose logging
--help Show help示例
# Start dashboard on port 8080
mcp-pulse dashboard --port 8080
# Proxy an SSE server
mcp-pulse proxy --target http://localhost:3001 --port 3100
# Proxy a stdio server and stream its output
mcp-pulse proxy:stdio -- npx @modelcontextprotocol/server-github
# Run alerting engine
mcp-pulse alert --threshold 5 --webhook https://hooks.example.com/alert
# Export last 1 hour to CSV
mcp-pulse export --format csv --hours 1 --output ./report.csv______________________________________________________________________
🔌 MCP服务器集成
官方服务器（SSE传输）
这些服务器与 mcp-pulse proxy 开箱即用：
| 服务器 | 包 | 状态 |
|---|---|---|
| 文件系统 | @modelcontextprotocol/server-filesystem | ✅ 已测试 |
| GitHub | @modelcontextprotocol/server-github | ✅ 已测试 |
| 松弛 | @modelcontextprotocol/server-slack | ✅ 已测试 |
| 谷歌地图 | @modelcontextprotocol/server-google-maps | ✅ 已测试 |
| 顺序思维 | @modelcontextprotocol/server-sequential-thinking | ✅ 已测试 |
| 哨兵 | @modelcontextprotocol/server-sentry | ✅ 已测试 |
| 勇敢的搜索 | @modelcontextprotocol/server-brave-search | ✅ 已测试 |
Stdio服务器
对于基于stdio的服务器，请使用 proxy:stdio:
mcp-pulse proxy:stdio -- python /path/to/your/mcp_server.py自定义服务器
要检测自定义MCP服务器，请添加脉冲中间件：
import { createPulseMiddleware } from 'mcp-pulse/middleware';
// In your MCP server setup:
server.addMiddleware(createPulseMiddleware({
endpoint: 'http://localhost:3000/pulse',
quiet: false, // suppress pulse logging
samplingRate: 1.0, // capture 100% of calls (0.0–1.0)
excludeTools: ['internal/debug'], // tools to skip
}));______________________________________________________________________
📡 仪表板API
仪表板公开了REST+WebSocket API。
REST端点
| 方法 | 端点 | 描述 | |
|---|---|---|---|
GET | /api/health | 健康检查 | |
GET | /api/metrics | 汇总指标汇总 | |
GET | /api/metrics/timeseries | 图表的时间序列数据 | |
GET | /api/calls | 分页通话记录 | |
GET | /api/calls/:id | 单次通话详情 | |
GET | /api/servers | 包含统计信息的服务器列表 | |
GET | /api/tools | 工具排行榜 | |
GET | /api/alerts | 警报历史记录 | |
POST | /api/alerts/config | 更新警报配置 | |
GET | /api/export | 下载导出（？格式=csv | json） |
WebSocket事件
// Connect to live stream
const ws = new WebSocket('ws://localhost:3000/live');
ws.on('message', (data) => {
const event = JSON.parse(data);
switch (event.type) {
case 'call:start': // MCP call initiated
case 'call:end': // MCP call completed (includes latency + status)
case 'call:error': // MCP call failed
case 'metrics:update': // Aggregated metrics (every 5s)
case 'alert:trigger': // Alert fired
case 'heartbeat': // Connection keepalive
}
});事件有效载荷
// call:end payload
{
id: 'call_abc123',
serverId: 'server_filesystem',
tool: 'filesystem.read_file',
duration: 42, // ms
status: 'success', // 'success' | 'error' | 'timeout'
request: { // Sanitized request (secrets removed)
method: 'tools/call',
params: { name: 'read_file', arguments: { path: '/projects/README.md' } }
},
response: {
content: [{ type: 'text', text: '...' }]
},
timestamp: '2026-03-21T14:30:00.000Z'
}
// alert:trigger payload
{
id: 'alert_001',
serverId: 'server_filesystem',
metric: 'error_rate',
value: 15.3, // percentage
threshold: 10.0,
window: '5m',
firedAt: '2026-03-21T14:30:00.000Z'
}______________________________________________________________________
⚙️ 配置
环境变量
MCP_PULSE_PORT=3000 # Dashboard port
MCP_PULSE_PROXY_PORT=3100 # Proxy port
MCP_PULSE_RETENTION=24 # Hours of data to keep
MCP_PULSE_TARGET= # Target MCP server URL (for proxy mode)
MCP_PULSE_SAMPLING=1.0 # Capture rate (0.0–1.0)
MCP_PULSE_AUTH_TOKEN= # Optional: require token for API
MCP_PULSE_WEBHOOK_URL= # Alert webhook URLconfig.json
放在项目根目录中或 ~/.mcp-pulse/config.json:
{
"dashboard": {
"port": 3000,
"auth": {
"enabled": false,
"token": "your-secret-token"
},
"retention": {
"hours": 24,
"maxCalls": 100000
}
},
"proxy": {
"port": 3100,
"target": "http://localhost:3001",
"protocol": "sse",
"sampling": 1.0
},
"alerts": [
{
"name": "High Error Rate",
"metric": "error_rate",
"threshold": 10,
"window": "5m",
"severity": "critical",
"actions": ["log", "webhook"]
},
{
"name": "High Latency",
"metric": "latency_p99",
"threshold": 2000,
"window": "5m",
"severity": "warning",
"actions": ["log"]
}
],
"export": {
"defaultFormat": "csv",
"includePayloads": false
}
}______________________________________________________________________
🧪 示例
示例1——监视文件系统MCP服务器
# Terminal 1: Start dashboard
mcp-pulse dashboard
# Terminal 2: Start filesystem MCP server via proxy
npx @modelcontextprotocol/server-filesystem $HOME/projects \
--mcp-pulse \
--mcp-pulse-port 3100 \
--mcp-pulse-target http://localhost:3100
# Terminal 3: Use the server (e.g. in Claude Desktop)
claude
# Open http://localhost:3000 to watch all file operations示例2-GitHub服务器故障警报
# Set webhook (e.g. Discord or Slack incoming webhook)
export MCP_PULSE_WEBHOOK_URL=https://discord.com/api/webhooks/xxx/yyy
# Start alert engine
mcp-pulse alert --threshold 5 --webhook $MCP_PULSE_WEBHOOK_URL
# Start GitHub MCP server
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx
npx @modelcontextprotocol/server-github \
--mcp-pulse \
--mcp-pulse-port 3100示例3——自定义仪表板嵌入
// Embed real-time mcp-pulse data into your own app
import { MCP PulseClient } from 'mcp-pulse/client';
const client = new MCP PulseClient({
dashboardUrl: 'http://localhost:3000',
apiKey: 'optional-token',
});
client.on('call:end', (call) => {
if (call.tool.includes('github') && call.status === 'error') {
console.error(`GitHub tool failed: ${call.tool}`, call.response);
}
});
await client.connect();______________________________________________________________________
🔒 安全
- 日志中没有秘密 --请求参数在存储之前会被扫描和编辑
- 有效载荷截断 --大响应被截断（可配置，默认10KB）
- 默认情况下仅限本地 --仪表板绑定到
127.0.0.1除非--public使用标志 - 可选身份验证 --set
MCP_PULSE_AUTH_TOKEN保护API - GDPR注释 --mcp脉冲在本地存储数据；除非导出，否则任何数据都不会离开您的机器
______________________________________________________________________
🤝 贡献
欢迎投稿！请阅读我们的 贡献指南 在提交PR之前。
# Development setup
git clone https://github.com/SergiuPogor/mcp-pulse.git
cd mcp-pulse
npm install
npm run dev # Watch mode + hot reload
npm run test # Run tests
npm run lint # Lint + format报告问题
请通过以下方式报告错误和功能请求 .包括：
- mcp脉冲版本(
mcp-pulse --version) - Node.js版本(
node --version) - MCP服务器名称和版本
- 重现步骤
______________________________________________________________________
📄 许可证
麻省理工学院©2026 Sergiu Pogor
______________________________________________________________________
如果你觉得有用，就把它标上。