{
  "markdown": "# ROS 2 MCP Server\n[<img src=\"https://img.shields.io/npm/v/ros-mcp\">](https://www.npmjs.com/package/ros-mcp)\n[<img src=\"https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF\" alt=\"Install in VS Code\">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522ros%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522ros-mcp%2522%255D%257D)\n\nA Model Context Protocol (MCP) server for ROS 2 that enables GitHub Copilot and other AI agents to interact with ROS 2 systems. This server provides tools for monitoring, debugging, and managing ROS 2 nodes, topics, services, and TF2 frames.\n\n### Quickstart\n\nAdd the following to `.vscode/mcp.json`\n\n```json\n{\n  \"servers\": {\n    \"ros\": {\n      \"command\": \"npx\",\n      \"args\": [\"ros-mcp\"]\n    }\n  }\n}\n```\n\nEnsure the server is selected in tools for vs code copilot\n\nYou're good to go!\ntry \"List active ros topics\" to test it out.\n\n## Features\n\n### Node Management\n- **list_ros_nodes**: List all running ROS 2 nodes with detailed information\n- **get_node_connections**: View all topics a node publishes to and subscribes from\n- **get_node_parameters**: List parameters for a specific node\n- **set_node_parameter**: Modify node parameters at runtime\n- **run_ros_node**: Launch a ROS 2 node from a package\n- **run_ros_launch**: Execute a launch file\n\n### Topic Monitoring\n- **list_ros_topics**: List all available topics with optional detailed type information\n- **get_topic_info**: Get detailed information about a specific topic\n- **monitor_topic**: Subscribe to a topic and collect messages for a specified duration (observational tool with wait capability)\n- **publish_to_topic**: Publish messages to a topic\n\n### Service Management\n- **list_ros_services**: List all available services\n- **call_service**: Call a service with optional parameters\n\n### TF2 Frame Monitoring\n- **monitor_tf2_frames**: Monitor TF2 transform frames and relationships (includes static and dynamic transforms)\n\n### System Visualization & Debugging\n- **generate_ros_graph**: Generate dependency graphs showing connections between nodes and topics (supports both text and Graphviz DOT format)\n- **check_ros_system_status**: Check overall system health, daemon status, and node/topic/service counts\n\n## Installation\n\n### Prerequisites\n- ROS 2 (tested with Humble and later)\n- Node.js 18+\n- npm or yarn\n\n### Manual Setup\n\n```bash\n# Clone or navigate to the repository\ncd /path/to/ROS-MCP\n\n# Install dependencies\nnpm install\n\n# Build the TypeScript\nnpm run build\n```\n\nWSL might need linking the nvm node to the default node path\n\nsudo ln -s ~/.nvm/versions/node/v24.11.0/bin/node /usr/local/bin/node\nsudo ln -s ~/.nvm/versions/node/v24.11.0/bin/npm /usr/local/bin/npm\n\n## Usage\n\n### Running the Server\n\n```bash\n# Direct execution (recommended for MCP integration)\nnpm start\n\n# Development with ts-node\nnpm run dev\n```\n\n### With GitHub Copilot\n\nConfigure the MCP server in your GitHub Copilot settings:\n\n```json\n{\n  \"servers\": {\n    \"ros\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/ROS-MCP/build/index.js\"]\n    }\n  }\n}\n```\n\n## Tool Details\n\n### Observational Tools (with Wait Capability)\n\nSome tools are designed to collect data over time, allowing the agent to wait and observe:\n\n- **monitor_topic**: Waits for 1-30 seconds, collecting messages from a topic. Supports custom message count limits. Perfect for:\n  - Observing sensor data streams\n  - Verifying topic publishing patterns\n  - Debugging message throughput\n\n- **monitor_tf2_frames**: Observes TF2 frame transforms over a specified duration (1-30 seconds)\n\n### Tool Examples\n\n#### Monitor a Topic\n```\nTool: monitor_topic\nParameters:\n  - topic_name: \"/sensor_msgs/LaserScan\"\n  - duration_seconds: 5\n  - message_count: 10\n```\nThis collects up to 10 messages from the LaserScan topic over 5 seconds.\n\n#### Generate Node Graph\n```\nTool: generate_ros_graph\nParameters:\n  - output_format: \"text\" (or \"dot\" for Graphviz)\n```\nReturns a visual representation of how nodes and topics are connected.\n\n#### Monitor System Health\n```\nTool: check_ros_system_status\nParameters:\n  - include_diagnostics: true\n```\nProvides comprehensive system status including daemon health, active nodes, and services.\n\n## Architecture\n\nThe server is built with:\n- **@modelcontextprotocol/sdk**: MCP framework for agent communication\n- **Zod**: Type-safe parameter validation\n- **Node.js Child Process**: Command execution for ROS 2 CLI tools\n\n## How It Works\n\n1. **Command Execution**: Each tool executes the corresponding `ros2` CLI command\n2. **Output Parsing**: Results are parsed and formatted for agent consumption\n3. **Timeout Handling**: Observational tools use configurable timeouts to collect data\n4. **Error Handling**: Commands that fail gracefully return error messages\n\n## Designing Tools for Agent Observation\n\nThis MCP server follows patterns that work well with AI agents:\n\n1. **Blocking Observational Operations**: Tools like `monitor_topic` block for the specified duration, allowing agents to naturally await results\n2. **Bounded Time Windows**: All monitoring tools have maximum durations (typically 5-30 seconds) to prevent indefinite waits\n3. **Progressive Data Collection**: Tools collect data incrementally and return results at the end of the observation window\n4. **Clear Output Format**: Results are structured text that agents can easily parse and reason about\n\n## Example Usage with Copilot\n\nA Copilot agent using this MCP can:\n\n```\nAgent: \"What topics are currently being published?\"\n[Uses: list_ros_topics]\n\nAgent: \"Let me observe the /cmd_vel topic for 5 seconds\"\n[Uses: monitor_topic with topic_name=\"/cmd_vel\", duration_seconds=5]\n[Waits 5 seconds for data collection]\n\nAgent: \"Here are the velocity commands being sent: [parsed data]\"\n\nAgent: \"Show me how all nodes are connected\"\n[Uses: generate_ros_graph with output_format=\"text\"]\n\nAgent: \"Let me try publishing a test message to the /cmd_vel topic\"\n[Uses: publish_to_topic]\n\nAgent: \"Let me check if any node is having issues\"\n[Uses: check_ros_system_status with include_diagnostics=true]\n```\n\n## Limitations\n\n- Some ROS 2 CLI commands require the ROS 2 environment to be properly sourced\n- TF2 monitoring requires the `tf2_tools` package to be installed\n- The server executes commands in the current environment - ensure ROS 2 is properly installed\n- Long-running operations may timeout; adjust duration parameters as needed\n\n## Future Enhancements\n\n- Integration with ROS 2 bag recording/playback\n- Parameter server monitoring\n- Action client/server interface\n- Live rqt plugin integration\n- Rviz2 data streaming\n- Custom message type parsing\n- CLI\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please ensure all tools handle errors gracefully and include proper parameter validation.\n",
  "bytes": 6845,
  "sha": "64de7da7cfd24e28c9ff14ea284bf1b4584e50c2827d7f71e6049abb74bdbc95",
  "repo_slug": "husain-zaidi/ros-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_husain_zaidi_ros_mcp_16b64b6a/readme"
}