Free SKILL.md scraped from GitHub. Clone the repo or copy the file directly into your Claude Code skills directory.
npx versuz@latest install vivekkarmarkar-claude-code-os-skills-mcp-healthgit clone https://github.com/VivekKarmarkar/claude-code-os.gitcp claude-code-os/SKILL.MD ~/.claude/skills/vivekkarmarkar-claude-code-os-skills-mcp-health/SKILL.md--- name: mcp-health description: Check the health of all MCP server connections in the current Claude Code session. Use when the user says "check MCP", "are my servers connected", "why is Telegram not working", "MCP health", "connection issues", "messages not coming through", "is the bot connected", "check connections", or when experiencing any MCP-related connectivity problems. Also use proactively when starting a session with channels/plugins to verify everything is running correctly. user-invocable: true allowed-tools: - Bash - Read - Glob --- # /mcp-health — MCP Server Connection Health Check Arguments passed: `$ARGUMENTS` ## Argument Handling Parse `$ARGUMENTS` to determine scope: - **No arguments** (empty or "all") → check ALL MCP servers (default) - **"quick"** → check all, dashboard only, no fixes - **"fix"** → check all, automatically resolve issues - **One or more server names** (e.g., "chrome", "telegram", "chrome, telegram") → check ONLY those servers Server name matching is case-insensitive. Map common names to their MCP prefixes: - `chrome` → `mcp__claude-in-chrome__*` tools - `telegram` → `mcp__plugin_telegram_telegram__*` tools / telegram bun process - `playwright` → `mcp__plugin_playwright_playwright__*` tools - `memory` → `mcp__memory__*` tools - `voicemode` → `mcp__voicemode__*` tools - `codex` → `mcp__codex-cli__*` tools - `pubmed` → `mcp__claude_ai_PubMed__*` tools If arguments are server names, **skip discovery** (Step 1) and jump straight to checking only the named servers. If no arguments or "all", run full discovery. ## Workflow ### Step 1: Discover MCP Servers (skip if specific servers were requested) Find all configured MCP servers: ```bash # Check for MCP config files find ~/.claude -name ".mcp.json" -o -name "mcp.json" 2>/dev/null # Check plugin cache for MCP configs find ~/.claude/plugins -name ".mcp.json" 2>/dev/null # List running MCP-related processes ps aux | grep -E '(bun|node).*(server|mcp)' | grep -v grep ``` ### Step 1b: Discover Non-Process MCP Servers Some MCP servers don't run as local processes — they connect via browser extensions, HTTP, or other transports. Check for these too: ```bash # Chrome MCP (browser extension) — check if tools are available # Try loading a chrome MCP tool to see if the extension is connected # If mcp__claude-in-chrome__* tools are in the available tools list, it's connected # Check for any HTTP-based MCP servers in config files grep -r "http" ~/.claude/plugins/cache/*/.*mcp.json 2>/dev/null | head -10 # Check for voicemode or other non-process MCP servers ps aux | grep -iE '(voicemode|chrome|claude-in)' | grep -v grep ``` For Chrome MCP specifically: attempt to call `mcp__claude-in-chrome__tabs_context_mcp`. If it responds, the extension is connected. If it errors, report it as DOWN. ### Step 2: Check Each Server For each discovered MCP server: **Process-Based Servers (bun/node):** - Is the process running? - What's its CPU and memory usage? - How long has it been running? - Is its parent process alive (or is it orphaned)? **Extension/HTTP-Based Servers (Chrome MCP, etc.):** - Can you call a basic tool? (e.g., tabs_context_mcp for Chrome) - Is the browser running? - Report connection status based on tool availability **Connection Health:** - Check stdin/stdout file descriptors — are pipes intact? - Is the process responsive or spinning? **Conflict Detection:** - Are there multiple instances of the same server? - For Telegram: check for 409 Conflict patterns (multiple polling consumers) - For any bot: check if another service is using the same token/credentials ### Step 3: Check Channel-Specific Health **Telegram (if configured):** ```bash # Check access config cat ~/.claude/channels/telegram/access.json 2>/dev/null # Check for token grep -c "TELEGRAM_BOT_TOKEN" ~/.claude/channels/telegram/.env 2>/dev/null # Check for zombie approvals ls ~/.claude/channels/telegram/approved/ 2>/dev/null # Check inbox size du -sh ~/.claude/channels/telegram/inbox/ 2>/dev/null ``` ### Step 4: Report Present a health dashboard: ``` MCP Health Check ================ Server: telegram Process: PID 189375 (bun server.ts) Status: RUNNING CPU: 0.2% Memory: 93MB Uptime: 1h 23m Parent: ALIVE (claude PID 188176) Pipes: INTACT Conflicts: NONE Health: HEALTHY Server: [other] ... Overall: X/Y servers healthy Issues Found: - [any problems detected] Recommendations: - [suggested fixes] ``` Status levels: - **HEALTHY** — Running, low CPU, intact pipes, no conflicts - **DEGRADED** — Running but high CPU, or competing instances detected - **ZOMBIE** — Orphaned process, broken pipes, should be killed - **DOWN** — Not running, needs restart - **CONFLICT** — Multiple consumers competing for same resource ### Step 5: Offer Fixes For any non-healthy servers: - ZOMBIE → offer to kill (link to /zombie-hunter) - DOWN → suggest restart steps - CONFLICT → identify competing processes and suggest resolution - DEGRADED → diagnose root cause and suggest fix ## Special Modes - `$ARGUMENTS` = "fix" → check all servers AND automatically resolve issues (kill zombies, report what was fixed) - `$ARGUMENTS` = "quick" → check all servers, dashboard only, no fix offers