home / mcp / debug mcp server

Debug MCP Server

A debugging assistant that analyzes bugs and sends HTTP-based logs per project to a centralized endpoint.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ahao0150-debug-mcp": {
      "url": "https://example-mcp-server.local/mcp",
      "headers": {
        "LOG_FILE": ".debug/debug.log",
        "DEBUG_HOST": "localhost",
        "DEBUG_PORT": "37373"
      }
    }
  }
}

You use this MCP server to automate debugging by analyzing bugs, injecting HTTP-based debug logs, and iterating fixes with real-time feedback. Logs are sent over HTTP to a central endpoint, stored per project, and the system cleans up after you finish debugging. This makes debugging reproducible, traceable, and safe to run across devices and environments.

How to use

Describe the bug to the AI, let it analyze potential causes, detect your environment, and generate an HTTP-based debug template. You then insert the debug code into your project files, restart as needed, and observe logs in the centralized, project-scoped store.

How to install

# Install and start the MCP server
npm install
npm run build
npm start

Configuration and usage notes

Key setup options include how logs are sent, where they are stored, and how you connect your client projects. The server exposes automatic port assignment for its HTTP log endpoint; you can override with environment variables if needed.

{
  "mcpServers": {
    "debug-mcp": {
      "command": "npm",
      "args": ["start"],
      "env": {
        "DEBUG_HOST": "localhost"
      }
    }
  }
}

Cross-device debugging and network setup

To debug from another device on your network, configure the host to listen on a LAN address and ensure firewalls permit the assigned port. Use the port discovery tool to find the actual port and construct the full URL for posting logs.

Useful workflow (high level)

1) Describe the bug to the AI. 2) Let it analyze and detect environment. 3) Get an HTTP-based debug template. 4) Manually insert the debug code into your file at the chosen location. 5) Restart and test. 6) Read the project logs with the read tool. 7) Iterate until you see expected logs and behavior. 8) When the issue is resolved, perform automatic cleanup of debug code and markers.

Troubleshooting

If logs do not appear, verify the port from the port discovery tool, confirm the server is running, and ensure the project path is correct. Check for any network or firewall blocks between the client and the MCP server.

Available tools

analyze_bug

Analyzes a bug description to suggest possible causes and next steps.

detect_environment

Detects the runtime environment of a given file or project component.

get_debug_template

Generates an HTTP-based debug logging snippet tailored to the target environment.

read_debug_logs

Reads logs stored for a specific project to help verify what was captured.

clear_debug_logs

Clears all stored debug logs for a given project.

list_debug_blocks

Lists all temporary debug code blocks within the project files.