Skip to main content
Glama

Autoware MCP Integration

License ROS2 Autoware

The Autoware MCP Server provides a universal bridge between ANY AI agent (Claude, GPT, Gemini, or custom agents) and the Autoware autonomous driving stack through the Model Context Protocol (MCP). This enables AI-driven mission planning, real-time vehicle control, and adaptive decision-making for autonomous vehicles.

Autonomous Driving Demo

Click the image above to watch the full autonomous driving demo

Key Features

  • Universal AI Support: Works with any MCP-compatible AI agent (Claude, GPT, Gemini, etc.)

  • Full Vehicle Control: Complete control over Autoware's autonomous driving features

  • Real-Time Monitoring: Concurrent monitoring of perception, planning, and vehicle state

  • Launch Management: Start, stop, and manage ROS2 launch sessions

  • Safety Systems: Comprehensive safety validation at every level

  • Mission Execution: Support for complex multi-step missions with waypoints

Quick Start

Prerequisites

  • Ubuntu 22.04 LTS

  • ROS2 Humble

  • Python 3.10+

  • Autoware 0.45.1

Installation

# Clone the repository
git clone https://github.com/your-org/autoware-mcp.git
cd autoware-mcp

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies with uv
uv sync --all-extras --dev

Basic Usage

  1. Start the MCP Server:

# Source your ROS2/Autoware workspace
source ~/autoware/install/setup.bash

# Start the MCP server
uv run autoware-mcp
  1. Connect with Claude Code: Add to your Claude Code configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "autoware": {
      "command": "uv",
      "args": ["run", "autoware-mcp"],
      "env": {
        "ROS_DOMAIN_ID": "your_domain_id"
      }
    }
  }
}
  1. Example Prompts for AI Agents:

Since AI agents may not have specific knowledge about autonomous driving, use clear, step-by-step prompts:

To launch a planning simulation:

Please launch a planning simulation for Autoware using the MCP tools. 
Use the start_launch tool with the planning_simulation_mcp.launch.py file.

To run an autonomous driving sequence:

Please run the complete autonomous driving sequence:
1. Initialize the vehicle's localization at the starting position
2. Clear any existing route and set a new route to the goal position
3. Change the operation mode to autonomous
4. Monitor the vehicle's progress until it reaches the destination
5. Stop the simulation when complete

To monitor vehicle state:

Please check the current vehicle state including position, speed, and route status
using the get_vehicle_state and get_current_route MCP tools.

Related MCP server: ros2-mcp-server

Available MCP Tools

System Management

  • health_check - Get complete system health status

  • check_autoware_status - Check running Autoware components

  • verify_ros2_environment - Verify ROS2 setup

Launch Management

  • start_launch - Start ROS2 launch files

  • stop_launch - Stop launch sessions

  • list_launch_sessions - View active sessions

  • get_session_status - Get detailed session information

Vehicle Control

  • set_operation_mode - Change between stop/autonomous/local/remote modes

  • initialize_localization - Set initial vehicle pose

  • set_route - Set route to destination

  • set_route_points - Set route with waypoints

  • get_current_route - Get current route status

Vehicle Monitoring

  • get_vehicle_state - Get vehicle position, speed, and kinematics

  • monitor_operation_mode - Monitor current operation mode

  • monitor_localization_state - Check localization status

  • monitor_motion_state - Monitor motion readiness

ROS2 Interface

  • list_ros2_nodes - List all active ROS2 nodes

  • list_ros2_topics - List all ROS2 topics

  • list_ros2_services - List all ROS2 services

  • call_ros2_service - Call any ROS2 service

  • publish_to_topic - Publish to any ROS2 topic

  • echo_topic_messages - Capture messages from topics

Documentation

For comprehensive documentation, please refer to the Developer Guide

Configuration

Create a configuration file config/custom.yaml:

mcp_server:
  host: 0.0.0.0
  port: 8080
  
autoware:
  ros_domain_id: 42
  ad_api_url: http://localhost:8888
  
safety:
  max_velocity: 50.0  # m/s
  max_acceleration: 3.0  # m/s²
  emergency_deceleration: -8.0  # m/s²

Development

Running Tests

# Unit tests
pytest tests/unit -v

# Integration tests (requires Autoware)
pytest tests/integration -v

# Simulation tests
pytest tests/simulation -v

# All tests with coverage
pytest --cov=autoware_mcp --cov-report=html

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

Safety Notice

WARNING: This system is designed for research and development purposes. Always ensure:

  • A safety driver is present during real vehicle testing

  • Emergency stop mechanisms are properly configured

  • All safety validations are enabled

  • Testing is conducted in controlled environments

Troubleshooting

Common Issues

  1. ROS2 Connection Issues:

export ROS_DOMAIN_ID=42
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
  1. MCP Server Not Responding:

  • Check firewall settings

  • Verify Autoware is running

  • Check logs: tail -f logs/mcp_server.log

  1. Performance Issues:

  • Monitor resource usage: htop, nvidia-smi

  • Check ROS2 topics: ros2 topic hz /topic_name

  • Review latency metrics in Grafana dashboard

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

Support

For issues and questions:

Roadmap

  • Multi-vehicle coordination support

  • Enhanced perception monitoring

  • Cloud-based mission management

  • V2X communication integration

  • Advanced ML-based planning

  • Simulation environment integration


Note: This project is under active development. APIs and features may change.

Available Tools

57 tools
analyze_driving_sceneB

Analyze complete driving scene with all sensors. Returns annotated images, detected objects, traffic lights, and driving recommendations for AI decision making.

Returns: Complete scene analysis with images, objects, and recommendations

Inputs: no named parameters. Returns: object

call_ros2_serviceA

Call any ROS2 service directly.

This is a powerful generic tool that can call any ROS2 service in the system. Use 'list_ros2_services' to discover available services.

Examples:

  • Clear route: call_ros2_service("/api/routing/clear_route", "autoware_adapi_v1_msgs/srv/ClearRoute", {})

  • Enable control: call_ros2_service("/api/operation_mode/enable_autoware_control", "std_srvs/srv/Trigger", {})

  • Accept start: call_ros2_service("/api/motion/accept_start", "std_srvs/srv/Trigger", {})

Returns:

  • success: Whether the service call succeeded

  • response: The service response data

  • error: Error message if call failed

Inputs: service_name (required), service_type (required), request. Returns: object

capture_camera_viewA

Capture current camera view and save as image file. Returns path to image that can be viewed with Read tool.

Args: camera: Camera to capture from (front, rear, left, right, traffic_light)

Returns: Dictionary with image_path that can be read with Read tool

Inputs: camera. Returns: object

check_autoware_statusA

Check the current status of running Autoware components.

Analyzes the ROS2 graph to identify:

  • Active Autoware nodes by category (perception, planning, control, etc.)

  • Autoware-specific topics

  • Component health status

Returns detailed status of running Autoware components.

Inputs: no named parameters. Returns: object

cleanup_orphansA

Clean up orphaned processes from stale MCP instances.

Scans for sessions from dead MCP servers and terminates them. Ensures no zombie processes remain after MCP crashes.

Returns: Information about cleaned up sessions

Inputs: no named parameters. Returns: object

echo_topic_messagesB

Capture and return messages from a ROS2 topic.

Args: topic_name: Name of the topic to echo count: Number of messages to capture (default: 1)

Returns: Captured messages from the topic.

Inputs: topic_name (required), count. Returns: object

generate_custom_nodeA

Generate a custom ROS2 node template.

Creates node files in .autoware-mcp/generated/nodes/ with versioning.

Args: name: Name of the node language: Programming language (python or cpp) node_type: Type of node (basic, service, action) interfaces: List of topics/services to interface with

Returns: Path to generated node file

Inputs: name (required), language, node_type, interfaces. Returns: object

generate_launch_fileA

Generate a ROS2 launch file for AI development.

Creates launch files in .autoware-mcp/generated/launches/ with versioning. Templates available: perception_pipeline, planning_pipeline, control_pipeline

Args: name: Name for the launch file (without extension) components: List of components/nodes to include template: Optional template name includes: Other launch files to include remappings: Topic remappings parameters: Parameters to set

Returns: Path to generated launch file and metadata

Inputs: name (required), components (required), includes, template, +2 more. Returns: object

generate_node_configA

Generate configuration file for a ROS2 node.

Creates config files in .autoware-mcp/generated/configs/ with versioning.

Args: node_name: Name of the node parameters: Parameters to configure format: Config format (yaml or json)

Returns: Path to generated config file

Inputs: node_name (required), parameters (required), format. Returns: object

get_configurationA

Get current MCP server configuration.

Returns all configuration parameters including:

  • Autoware workspace path

  • ROS distribution

  • Server settings

Inputs: no named parameters. Returns: object

get_cooperation_policiesA

Get current cooperation policies.

Returns: Active cooperation policies

Inputs: no named parameters. Returns: object

get_current_routeB

Get current route state.

Returns: Current route information including waypoints and progress

Inputs: no named parameters. Returns: object

get_detected_objectsA

Get list of currently detected objects (vehicles, pedestrians, etc.) with positions, velocities, and classifications.

Args: object_type: Filter by object type (all, vehicle, pedestrian, bicycle, motorcycle)

Returns: List of detected objects with properties

Inputs: object_type. Returns: object

get_launch_errorsB

Get error diagnostics from a launch session.

Retrieves error messages and stderr logs.

Args: session_id: Session ID to get errors from

Returns: Error information and diagnostics

Inputs: session_id (required). Returns: object

get_node_infoA

Get detailed information about a specific ROS2 node.

Args: node_name: Full name of the node (including namespace)

Returns: Node information including publishers, subscribers, services, and parameters.

Inputs: node_name (required). Returns: object

get_perception_snapshotA

Get comprehensive perception snapshot with camera, LiDAR, and object detection overlays. Returns multiple images and object data.

Returns: Dictionary with multiple image paths and detection data

Inputs: no named parameters. Returns: object

get_session_logsA

Get buffered logs from a launch session.

Retrieves the last N lines from session log files.

Args: session_id: Session ID lines: Number of lines to retrieve stream: Log stream to read (stdout or stderr)

Returns: Log content and metadata

Inputs: session_id (required), lines, stream. Returns: object

get_session_statusB

Get detailed status of a specific launch session.

Args: session_id: Session ID to query

Returns: Detailed session status including PID/PGID, state, nodes

Inputs: session_id (required). Returns: object

get_system_statusA

Get current system resource usage and status.

Returns:

  • CPU usage and frequency

  • Memory usage

  • Disk usage

  • Network interfaces

  • Process counts

Inputs: no named parameters. Returns: object

get_topic_frequencyA

Measure the publishing frequency of a ROS2 topic.

Args: topic_name: Name of the topic to measure duration: How long to measure (default: 5 seconds)

Returns: Frequency information including average Hz.

Inputs: topic_name (required), duration. Returns: object

get_topic_infoA

Get detailed information about a specific ROS2 topic.

Args: topic_name: Name of the topic (e.g., "/tf", "/map")

Returns: Topic information including message type, publisher count, subscriber count.

Inputs: topic_name (required). Returns: object

get_vehicle_stateA

Get comprehensive vehicle state including dimensions, status, and kinematics.

This unified tool combines vehicle dimensions, current status (speed, gear, steering), and kinematics (position, orientation, velocity) into a single response.

Returns: Complete vehicle state information including: - dimensions: Vehicle physical dimensions - status: Current gear, speed, steering angle - kinematics: Position, orientation, velocities - timestamp: When the data was collected

Inputs: no named parameters. Returns: object

health_checkA

Get complete health status of the Autoware MCP server.

Returns comprehensive health information including:

  • System resources (CPU, memory, disk)

  • ROS2 status and active nodes/topics

  • Autoware workspace configuration

  • Overall health status

Inputs: no named parameters. Returns: Health check response model.

initialize_localizationC

Initialize localization with a pose.

Args: pose: Initial pose with position and orientation pose_with_covariance: Optional pose covariance matrix

Returns: Localization response with success status

Inputs: pose (required), pose_with_covariance. Returns: Response model for localization operations.

list_generated_filesA

List all AI-generated files in the project.

Shows generated launches, nodes, and configs.

Returns: Dictionary of generated files by category

Inputs: no named parameters. Returns: object

list_launch_sessionsA

List all launch sessions with their current status.

Returns comprehensive information about all tracked launch sessions.

Returns: List of session information dictionaries

Inputs: no named parameters. Returns: result

list_mrm_behaviorsA

List available MRM behaviors.

Returns: List of available MRM behavior types

Inputs: no named parameters. Returns: result

list_ros2_nodesA

List all active ROS2 nodes in the system.

Returns list of node names with their namespaces.

Inputs: no named parameters. Returns: result

list_ros2_servicesB

List all active ROS2 services in the system.

Returns list of service names that can be called.

Inputs: no named parameters. Returns: result

list_ros2_topicsA

List all active ROS2 topics in the system.

Returns list of topic names.

Inputs: no named parameters. Returns: result

monitor_diagnosticsC

Get real-time diagnostics status.

Returns: Comprehensive diagnostics information

Inputs: no named parameters. Returns: object

monitor_localization_stateB

Monitor localization initialization state.

Returns: Current localization state and quality metrics

Inputs: no named parameters. Returns: object

monitor_motion_stateA

Monitor current motion state.

Returns: Current motion state and readiness

Inputs: no named parameters. Returns: object

monitor_mrm_stateB

Monitor current MRM state.

Returns: Current MRM state and active behaviors

Inputs: no named parameters. Returns: object

monitor_operation_modeA

Monitor current operation mode state.

Returns: Current operation mode and control state

Inputs: no named parameters. Returns: object

monitor_system_heartbeatB

Monitor system heartbeat.

Returns: System heartbeat status

Inputs: no named parameters. Returns: object

pause_launchB

Pause a running launch session using SIGSTOP.

Suspends all processes in the session's process group.

Args: session_id: Session ID to pause

Returns: Status of the pause operation

Inputs: session_id (required). Returns: object

publish_to_topicA

Publish a message to any ROS2 topic.

This tool allows publishing to any ROS2 topic with the appropriate message type. Use 'get_topic_info' to discover the message type for a topic.

Examples:

  • Publish twist: publish_to_topic("/cmd_vel", "geometry_msgs/msg/Twist", {"linear": {"x": 1.0}, "angular": {"z": 0.5}})

  • Publish initial pose: publish_to_topic("/initialpose", "geometry_msgs/msg/PoseWithCovarianceStamped", {...})

Returns:

  • success: Whether the publish succeeded

  • error: Error message if publish failed

Inputs: message (required), topic_name (required), message_type (required). Returns: object

request_mrmC

Request a Minimum Risk Maneuver (MRM).

Args: behavior: MRM behavior type reason: Optional reason for MRM request

Returns: MRM response with success status and current state

Inputs: behavior (required), reason. Returns: Response model for MRM operations.

reset_diagnosticsB

Reset diagnostics.

Returns: Success status and message

Inputs: no named parameters. Returns: object

restart_launchA

Restart a launch session (stop and start with same config).

Creates a new session with the same launch file and parameters.

Args: session_id: Session ID to restart

Returns: Status with old and new session IDs

Inputs: session_id (required). Returns: object

resume_launchA

Resume a paused launch session using SIGCONT.

Continues all processes in the session's process group.

Args: session_id: Session ID to resume

Returns: Status of the resume operation

Inputs: session_id (required). Returns: object

send_acceleration_commandC

Send acceleration control command.

Args: acceleration: Target acceleration in m/s²

Returns: Command acknowledgment

Inputs: acceleration (required). Returns: object

send_cooperation_commandsB

Send cooperation commands.

Args: commands: Cooperation commands

Returns: Command acknowledgment

Inputs: commands (required). Returns: object

send_pedals_commandC

Send pedals control command.

Args: throttle: Throttle position (0-1) brake: Brake position (0-1)

Returns: Command acknowledgment

Inputs: brake, throttle. Returns: object

send_steering_commandA

Send steering control command.

Args: steering_angle: Steering angle in radians

Returns: Command acknowledgment

Inputs: steering_angle (required). Returns: object

send_velocity_commandC

Send velocity control command.

Args: velocity: Target velocity in m/s

Returns: Command acknowledgment

Inputs: velocity (required). Returns: object

set_cooperation_policiesB

Set cooperation policies.

Args: policies: Cooperation policies configuration

Returns: Success status and active policies

Inputs: policies (required). Returns: object

set_operation_modeA

Change vehicle operation mode.

Modes:

  • stop: Stop vehicle operation

  • autonomous: Switch to autonomous driving

  • local: Switch to local manual control

  • remote: Switch to remote control

Args: mode: Operation mode (stop, autonomous, local, remote) transition_time: Maximum time to wait for transition

Returns: Operation mode response with success status and current mode

Inputs: mode (required), transition_time. Returns: Response model for operation mode operations.

set_routeB

Set a route to a goal pose.

Args: goal_pose: Goal pose with position and orientation waypoints: Optional waypoints option: Route options

Returns: Route response with success status and route information

Inputs: goal_pose (required), option, waypoints. Returns: Response model for route operations.

set_route_pointsB

Set a route with specific waypoints.

Args: waypoints: List of waypoints with position and orientation option: Optional route options

Returns: Route response with success status and route information

Inputs: waypoints (required), option. Returns: Response model for route operations.

start_launchA

Start a ROS2 launch file and track the session.

Creates a new launch session with PID/PGID tracking for proper cleanup. Sessions persist across MCP reconnections.

Args: launch_file: Path to the launch file parameters: Optional parameters to pass to launch launch_args: Optional command line arguments

Returns: Session information including ID, PID, PGID, and status

Inputs: launch_file (required), parameters, launch_args. Returns: object

stop_launchA

Stop a launch session gracefully or forcefully.

Sends SIGTERM to process group, waits for timeout, then SIGKILL if needed.

Args: session_id: Session ID to stop force: If True, use SIGKILL immediately timeout: Timeout for graceful shutdown

Returns: Status of the stop operation

Inputs: session_id (required), force, timeout. Returns: object

test_launch_fileC

Test a launch file without fully starting nodes (dry-run).

Validates syntax and optionally attempts to start/stop.

Args: file_path: Path to launch file to test dry_run: If True, only validate without starting

Returns: Test results with any errors or warnings

Inputs: file_path (required), dry_run. Returns: object

validate_launch_fileA

Validate launch file syntax and structure.

Checks Python syntax and required functions.

Args: file_path: Path to launch file to validate

Returns: Validation results with success status and any errors

Inputs: file_path (required). Returns: object

verify_ros2_environmentA

Verify ROS2 environment is properly set up.

The MCP server expects users to source their ROS2/Autoware environment before starting the server. This tool checks if the environment is ready.

Returns:

  • ROS2 availability and version

  • Environment variables status

  • Whether system is ready for MCP operations

Inputs: no named parameters. Returns: object

visualize_lidar_sceneA

Create visualization of LiDAR pointcloud data. Returns image showing 3D scene from specified viewpoint.

Args: view_type: Visualization viewpoint (bev, front, side, rear)

Returns: Dictionary with visualization image path

Inputs: view_type. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 57 tools

    Disambiguation4/5

    Most tools have distinct purposes, covering ROS2 operations, vehicle control, perception, monitoring, routing, launch management, and code generation. Minor overlaps exist (e.g., set_route/set_route_points, validate_launch_file/test_launch_file, get_detected_objects/analyze_driving_scene) but descriptions help disambiguate.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case (e.g., list_ros2_topics, get_vehicle_state, send_velocity_command). No mixing of conventions or camelCase, ensuring predictability.

    Tool Count2/5

    With 57 tools, the server exceeds the recommended 25-tool threshold for coherence. While Autoware is complex, several tools could be merged (e.g., validate/test launch, route variants) to reduce bloat and cognitive load.

    Completeness4/5

    The tool set covers core Autoware workflows: perception, localization, routing, control, monitoring, launch management, and code generation. Minor gaps exist (e.g., bag recording, dynamic parameter adjustment), but the surface is largely complete.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables large language models to interact with ROS robots seamlessly, allowing natural language control, real-time sensor monitoring, and autonomous task execution without modifying existing robot code.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      World-first unified MCP gateway + Control Barrier Function (CBF-QP) safety engine for agentic robotics, enabling LLMs to control physical robots with mathematically proven safety.
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      ROS2 MCP server that bridges AI agents (Claude Code, OpenClaw, Cursor) to ROS2, allowing them to read topics, call services, control robots, and wrap telemetry into verifiable hash-chained proof bundles.
      6
      MIT