{"id":25924950,"url":"https://github.com/willibrandon/cursormcpmonitor","last_synced_at":"2026-05-08T05:55:12.404Z","repository":{"id":280386745,"uuid":"941819211","full_name":"willibrandon/CursorMCPMonitor","owner":"willibrandon","description":"Real-time monitoring tool for Model Context Protocol (MCP) interactions in Cursor AI editor. Track, analyze, and debug AI context exchanges between LLM clients and servers. Supports log rotation, pattern matching, and color-coded event visualization.","archived":false,"fork":false,"pushed_at":"2025-03-03T05:59:58.000Z","size":57,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-03T06:26:04.838Z","etag":null,"topics":["ai-tools","cursor-ai","debugging","developer-tools","dotnet","llm-tools","logging","mcp","model-context-protocol","monitoring","real-time-monitoring"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/willibrandon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-03T05:22:43.000Z","updated_at":"2025-03-03T06:00:02.000Z","dependencies_parsed_at":"2025-03-03T06:36:20.679Z","dependency_job_id":null,"html_url":"https://github.com/willibrandon/CursorMCPMonitor","commit_stats":null,"previous_names":["willibrandon/cursormcpmonitor"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2FCursorMCPMonitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2FCursorMCPMonitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2FCursorMCPMonitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2FCursorMCPMonitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/willibrandon","download_url":"https://codeload.github.com/willibrandon/CursorMCPMonitor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241718416,"owners_count":20008571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","cursor-ai","debugging","developer-tools","dotnet","llm-tools","logging","mcp","model-context-protocol","monitoring","real-time-monitoring"],"created_at":"2025-03-03T18:33:26.614Z","updated_at":"2026-05-08T05:55:12.399Z","avatar_url":"https://github.com/willibrandon.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cursor MCP Monitor\n\nA .NET console application that monitors Model Context Protocol (MCP) interactions in the Cursor AI editor. This tool helps developers debug and analyze MCP server-client communications by monitoring log files in real-time.\n\n## What is MCP?\n\nThe Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. It follows a client-server architecture where:\n- **MCP Hosts** (like Cursor) connect to multiple servers\n- **MCP Clients** maintain 1:1 connections with servers\n- **MCP Servers** expose specific capabilities through the standardized protocol\n- **Local Data Sources** and **Remote Services** are accessed securely through MCP servers\n\n## Features\n\n- Real-time monitoring of MCP client-server interactions in Cursor:\n  - Client creation and connection events\n  - Server offering listings and capabilities\n  - Protocol errors and warnings\n  - Client lifecycle transitions\n- Monitors the Cursor logs directory for new MCP log files\n- Parses and color-codes different message types:\n  - Green: Client creation and successful connections\n  - Yellow: Server offering listings\n  - Red: Protocol errors and client closures\n  - Gray: General information messages\n- Supports log rotation and file truncation\n- Cross-platform support (Windows, macOS, Linux)\n- Smart error handling with exponential backoff and retry logic\n- Configurable polling interval and log file patterns\n- Command-line interface for easy customization\n- **Structured logging** with Serilog for improved observability:\n  - Console logging with formatted output\n  - File logging with daily rotation\n  - Contextual properties (machine name, thread ID, etc.)\n  - Log level filtering and output customization\n\n## Interactive Dashboard\n\nThe application includes a web-based dashboard for monitoring and analysis, accessible at `http://localhost:5050` when the application is running. The dashboard features real-time event streaming through WebSocket connections with automatic reconnection handling and event rate monitoring.\n\nThe terminal display shows timestamps with millisecond precision and color-coded message types for easy identification of different event types. Advanced search functionality includes text-based search with highlighting and keyboard shortcut support.\n\nA command palette (Ctrl/Cmd + P) provides quick access to common actions:\n- Clear logs (Ctrl/Cmd + K)\n- Copy visible entries (Ctrl/Cmd + C)\n- Toggle auto-scroll (Ctrl/Cmd + S)\n- Focus search (/)\n\nThe dashboard includes status indicators for WebSocket connection state, active client count, and events per second. It supports both dark and light themes with system theme detection.\n\n## Installation\n\nYou can install the tool globally using the .NET CLI:\n\n```bash\n# Install from NuGet.org\ndotnet tool install --global CursorMCPMonitor\n\n# Or install from GitHub Packages\ndotnet nuget add source --name github \"https://nuget.pkg.github.com/willibrandon/index.json\"\ndotnet tool install --global CursorMCPMonitor --add-source github\n```\n\nAfter installation, you can run the tool from anywhere using:\n```bash\ncursor-mcp --help\n```\n\nTo update to the latest version:\n```bash\ndotnet tool update --global CursorMCPMonitor\n```\n\nTo uninstall:\n```bash\ndotnet tool uninstall --global CursorMCPMonitor\n```\n\n## Configuration\n\nThe application can be configured through `appsettings.json`:\n\n```json\n{\n  \"LogsRoot\": null,\n  \"PollIntervalMs\": 1000,\n  \"LogPattern\": \"Cursor MCP.log\",\n  \"Verbosity\": \"Debug\",\n  \"Filter\": null,\n  \"Serilog\": {\n    \"MinimumLevel\": {\n      \"Default\": \"Debug\",\n      \"Override\": {\n        \"Microsoft\": \"Warning\",\n        \"System\": \"Warning\"\n      }\n    },\n    \"Enrich\": [ \"FromLogContext\", \"WithMachineName\", \"WithThreadId\" ],\n    \"Properties\": {\n      \"Application\": \"CursorMCPMonitor\"\n    }\n  },\n  \"Logging\": {\n    \"LogLevel\": {\n      \"Default\": \"Debug\",\n      \"Microsoft\": \"Warning\"\n    }\n  }\n}\n```\n\n- `LogsRoot`: The root directory to monitor for Cursor MCP logs. If null, defaults to:\n  - Windows: `%AppData%/Cursor/logs`\n  - macOS: `~/Library/Application Support/Cursor/logs`\n  - Linux: `~/.config/Cursor/logs`\n- `PollIntervalMs`: How often to check for new log lines (in milliseconds)\n- `LogPattern`: The log file pattern to monitor (supports glob patterns like \"Cursor MCP*.log\")\n- `Verbosity`: The verbosity level (Debug, Information, Warning, Error). Defaults to Debug to show all messages.\n- `Filter`: Optional text pattern to filter log content (only lines containing this text will be displayed)\n- `Serilog`: Configuration for structured logging (see [Serilog configuration](#serilog-configuration))\n\nYou can also override settings using environment variables:\n```bash\n# Windows\nset LogsRoot=C:\\CustomPath\\Cursor\\logs\nset PollIntervalMs=500\n# Linux/macOS\nexport LogsRoot=/custom/path/cursor/logs\nexport PollIntervalMs=500\n```\n\n### Serilog Configuration\n\nThe application uses Serilog for structured logging, which can be configured in the `appsettings.json` file:\n\n- `Serilog:MinimumLevel:Default`: The default minimum log level\n- `Serilog:MinimumLevel:Override`: Override minimum log levels for specific namespaces\n- `Serilog:Enrich`: Enrichers to add contextual information to logs\n- `Serilog:Properties`: Custom properties to include in all log events\n\nBy default, logs are written to:\n- Console: Formatted for human readability\n- Files: Stored in the `logs` directory with daily rotation as `cursormonitor-YYYYMMDD.log`\n\n## Command-Line Options\n\nYou can override configuration settings using command-line options:\n\n```bash\n# Specify a custom logs directory\ndotnet run -- --logs-root \"C:\\Users\\username\\AppData\\Roaming\\Cursor\\logs\"\n\n# Set a custom polling interval (500ms)\ndotnet run -- --poll-interval 500\n\n# Use a different log pattern (glob pattern support)\ndotnet run -- --log-pattern \"Cursor MCP*.log\"\n\n# Set verbosity level\ndotnet run -- --verbosity debug\n\n# Filter logs to only show lines containing specific text\ndotnet run -- --filter \"CreateClient\"\n\n# Combine multiple options\ndotnet run -- --logs-root \"/path/to/logs\" --poll-interval 500 --verbosity error --filter \"Error in MCP\"\n```\n\n## Building and Running\n\n### Prerequisites\n- .NET 9.0 SDK or later\n\n### Build\n```bash\ndotnet build\n```\n\n### Run\n```bash\ndotnet run\n```\n\n## Docker Support\n\nThe application includes Docker support. To build and run using Docker:\n\n```bash\n# Make sure you're in the repository root directory\ncd /path/to/CursorMCPMonitor\n\n# Build the image (note the -f flag to specify Dockerfile location)\ndocker build -t cursor-mcp-monitor -f src/CursorMCPMonitor/Dockerfile .\n\n# Run the container with volume mapping for logs\n# For Windows PowerShell:\ndocker run -it --rm -v \"$env:APPDATA\\Cursor\\logs:/app/logs\" -e LogsRoot=/app/logs cursor-mcp-monitor\n\n# For Windows CMD:\ndocker run -it --rm -v \"%APPDATA%\\Cursor\\logs:/app/logs\" -e LogsRoot=/app/logs cursor-mcp-monitor\n\n# For macOS/Linux:\ndocker run -it --rm -v \"$HOME/Library/Application Support/Cursor/logs:/app/logs\" -e LogsRoot=/app/logs cursor-mcp-monitor\n```\n\n\u003e **Important**: \n\u003e - Always run the Docker build command from the repository root directory, not from the project directory. This ensures that all necessary files are included in the build context.\n\u003e - When running the Docker container, you need to map your local Cursor logs directory into the container and set the `LogsRoot` environment variable to point to the mapped directory.\n\n## Logging and Observability\n\nThe application implements structured logging using Serilog, which provides several benefits:\n\n- **Contextual Information**: Each log entry includes contextual properties like machine name, thread ID, and source context\n- **Multiple Output Formats**: Logs are written to both console and files in formatted output\n- **Log Levels**: Different log levels (Debug, Information, Warning, Error, Fatal) help filter the most relevant information\n- **Structured Data**: Log events include structured data that can be queried and analyzed\n- **Log Files**: Log files are stored in the application's `logs` directory with daily rotation\n\nExample log format (console):\n```\n[2025-03-03 12:34:56.789] [INF] [CursorMCPMonitor.Services.LogProcessorService] CreateClient detected: Cursor MCP.log 2025-03-03 12:34:56.123 [info] a602: Handling CreateClient action\n```\n\nExample log format (file):\n```\n2025-03-03 12:34:56.789 +00:00 [INF] [CursorMCPMonitor.Services.LogProcessorService] CreateClient detected: Cursor MCP.log 2025-03-03 12:34:56.123 [info] a602: Handling CreateClient action\n```\n\n## Error Handling\n\nThe application includes advanced error handling:\n\n- Exponential backoff with jitter for file access errors\n- Automatic recovery from transient issues\n- Detailed error reporting with color-coded console output\n- File rotation and truncation detection\n- Structured error logging with contextual information\n\n## Use Cases\n\n- Debug MCP server implementations by monitoring client-server interactions\n- Analyze protocol messages and error patterns\n- Track client lifecycle and connection states\n- Monitor server capabilities and offerings\n- Verify correct protocol implementation\n- Track application performance and error rates through structured logs\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillibrandon%2Fcursormcpmonitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwillibrandon%2Fcursormcpmonitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillibrandon%2Fcursormcpmonitor/lists"}