wpilog-mcp: Model Context Protocol (MCP) Server for WPILib Logs

Ever wondered why your robot died with 30 seconds left? Or why auto worked in practice but not in competition?

wpilog-mcp lets you ask those questions in plain English. Load your robot's telemetry logs and have a conversation with your data.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants (like Claude) to securely access your local data and tools.

This project provides an MCP Server. Once configured, it acts as a "bridge" that gives your AI assistant the specific tools needed to read WPILOG files, analyze swerve performance, detect brownouts, and even pull match results from The Blue Alliance—all through a natural conversation.

The Power of AI Reasoning

Unlike traditional log viewers (like AdvantageScope) which require you to know exactly what to look for, wpilog-mcp allows you to ask high-level engineering and strategic questions. The AI doesn't just "query" data; it hypothesizes, investigates, and synthesizes.

1. The Autonomous "Post-Match Pit Boss"

Prompt: "We just finished Q68 and the drivers said the robot 'stuttered' during teleop. Investigate the log and tell the pit crew exactly what to check."

The AI's Reasoning: Claude will load the log, scan the get_ds_timeline for brownout events, use power_analysis to find which motor controller had the highest current spike at that exact timestamp, and check can_health for timeouts.
The Result: "I found a BROWNOUT_START at 42.5s. During this time, the 'Intake/Roller' current spiked to 60A while velocity was zero, suggesting a mechanical jam. Check the intake for debris or a bent mounting bracket."

2. Strategic "Cycle Time" Optimization

Prompt: "Compare our cycle times in Q74 vs Q68. Why were we slower in the second half of Q68?"

The AI's Reasoning: Claude will pull match results from TBA to see the scores, use analyze_cycles to calculate state-based efficiency, and correlate "dead time" with robot position data.
The Result: "Your scoring cycles in Q74 averaged 8.2s. In Q68, they slowed to 12.5s after the 60-second mark. I noticed that during those slower cycles, the robot was taking a much longer path around the 'Stage' obstacle—check if your autonomous path-finding or driver path was blocked."

3. Control Theory "Tuning Audit"

Prompt: "Look at our swerve drive performance in the last match. Is our steering PID too aggressive? Look for oscillation."

The AI's Reasoning: Claude will use analyze_swerve to identify the modules, call get_statistics on the steering error, and run find_peaks to look for high-frequency oscillations in the AppliedVolts.
The Result: "The Back-Left module is showing a 0.15s oscillation period in steering position while the robot is at a standstill. This suggests your P gain is slightly too high or your D gain is insufficient for the new modules."

Built by FRC Team 2363 Triple Helix using WPILib's official DataLogReader for guaranteed format compatibility.

See what's possible: Example Analysis Report - A complete match analysis generated from real robot logs.

Quick Start

1. Build

Built for JDK 17 binary compatibility. It is recommended to use the WPILib JDK, which the build tool attempts to locate automatically.

git clone https://github.com/TripleHelixProgramming/wpilog-mcp.git
cd wpilog-mcp
./gradlew shadowJar

2. Configure

Configuration location depends on how you're running Claude Code:

Environment	Config File
VS Code extension	`.mcp.json` in your project folder
Claude Code CLI	`~/.claude/settings.json`
Claude Desktop	See Claude Desktop section

Example configuration (macOS/Linux):

{
  "mcpServers": {
    "wpilog": {
      "command": "/Users/yourname/wpilib/2026/jdk/bin/java",
      "args": [
        "-jar", "/path/to/wpilog-mcp-0.2.0-all.jar",
        "-logdir", "/path/to/your/logs",
        "-team", "2363"
      ],
      "env": {
        "TBA_API_KEY": "your_tba_api_key"
      }
    }
  }
}

Example configuration (Windows):

{
  "mcpServers": {
    "wpilog": {
      "command": "C:\\Users\\Public\\wpilib\\2026\\jdk\\bin\\java.exe",
      "args": [
        "-jar", "C:\\path\\to\\wpilog-mcp-0.2.0-all.jar",
        "-logdir", "C:\\path\\to\\your\\logs",
        "-team", "2363"
      ],
      "env": {
        "TBA_API_KEY": "your_tba_api_key"
      }
    }
  }
}

Note: TBA key is optional. Without it, the server works normally but without match enrichment. Team number is extracted from log metadata when available, with -team as a fallback.

3. Use

Restart Claude Code. Then just ask:

What robot logs are available?

Load the qualification match 42 log and give me a summary

When did battery voltage drop below 11 volts?

Compare the commanded wheel speeds to actual wheel speeds

That's it! See Usage Examples for more.

Usage Examples

Browsing Logs

What robot logs are available?

The server parses filenames like 2024vadc_qm42.wpilog into friendly names like "VADC Qualification 42".

Basic Analysis

Load the robot log and give me a summary

Show me all entries related to the drivetrain

What Pose2d entries are available?

Robot Position

Show me where the robot was at the start and end of the match

Get statistics on the robot's X position - how much did it vary?

Threshold Events

When did battery voltage drop below 11 volts?

Find all times when robot speed exceeded 4 meters per second

Console Output

Search for any CAN errors in the console output

Find all vision-related messages in the logs

Swerve Analysis

Show me the swerve module states for the front left module

Compare commanded wheel speeds to actual wheel speeds

AdvantageKit Replay

Compare /RealOutputs/Drive/Pose with /ReplayOutputs/Drive/Pose

Multi-Log Analysis

Load both the practice and match logs, then compare battery statistics

Memory Management

Unload all logs to free up memory

Configuration Options

Command Line

Option	Description
`-logdir <path>`	Directory containing `.wpilog` files
`-team <number>`	Default team number for logs missing metadata
`-tba-key <key>`	The Blue Alliance API key for match data enrichment
`-maxlogs <n>`	Max number of logs to cache (default: 20)
`-maxmemory <mb>`	Max memory (MB) for log cache (alternative to `-maxlogs`)
`-debug`	Enable debug logging
`-help`	Show usage information

Environment variables:

WPILOG_DIR - Alternative to -logdir (command line takes precedence)
WPILOG_TEAM - Alternative to -team
TBA_API_KEY - Alternative to -tba-key

Cache limits: The server caches parsed logs in memory for fast access. By default, up to 20 logs are kept. Use -maxlogs to change this limit, or -maxmemory to set a memory-based limit instead (only used if -maxlogs is not set). The least recently used log is evicted when the limit is reached.

The Blue Alliance Integration

Get a free API key at thebluealliance.com/account.

When configured, the server enriches match logs with TBA data:

Match times - Corrects midnight timestamps from FMS
Scores - Your alliance's score and opponent's score
Win/Loss - Whether your team won the match
Alliance - Which alliance (red/blue) your team was on

Team number is extracted from each log file's metadata (DriverStation/FMS data), with the configured -team value as a fallback.

This data is automatically added to list_available_logs output for logs that have event/match/team metadata.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "wpilog": {
      "command": "/path/to/java",
      "args": ["-jar", "/path/to/wpilog-mcp-0.2.0-all.jar", "-logdir", "/path/to/logs"]
    }
  }
}

Other MCP Clients

This server uses stdio transport (JSON-RPC over stdin/stdout). Generic config:

{
  "command": "/path/to/java",
  "args": ["-jar", "/path/to/wpilog-mcp-0.2.0-all.jar"],
  "transport": "stdio"
}

See MCP Protocol for client implementations.

Available Tools

wpilog-mcp provides 35 tools organized into categories:

Category	Tools
Core	`load_log`, `list_entries`, `read_entry`, `get_entry_info`, `search_entries`, `get_statistics`, `compare_entries`, `get_types`
Log Browser	`list_available_logs`
Multi-Log	`list_loaded_logs`, `set_active_log`, `unload_log`, `unload_all_logs`
Search	`find_condition`, `search_strings`
Analysis	`detect_anomalies`, `find_peaks`, `rate_of_change`, `time_correlate`, `get_match_phases`
FRC-Specific	`analyze_swerve`, `power_analysis`, `can_health`, `compare_matches`, `get_code_metadata`
FRC Domain Analysis	`get_ds_timeline`, `analyze_vision`, `profile_mechanism`, `analyze_auto`, `analyze_cycles`, `analyze_replay_drift`
TBA Integration	`get_tba_status`
Export	`export_csv`, `generate_report`

For complete tool documentation with parameters and examples, see TOOLS.md.

Supported Data Types

Primitive Types

boolean, int64, float, double, string, raw, json, and arrays of each

WPILib Geometry Types

Type	Decoded Fields
`Pose2d`	`x`, `y`, `rotation_rad`, `rotation_deg`
`Pose3d`	`x`, `y`, `z`, `qw`, `qx`, `qy`, `qz`
`Translation2d/3d`	`x`, `y`, (`z`)
`Rotation2d`	`radians`, `degrees`
`Rotation3d`	`qw`, `qx`, `qy`, `qz`
`Transform2d/3d`	Same as Pose
`Twist2d/3d`	`dx`, `dy`, (`dz`), `dtheta`/(`rx`, `ry`, `rz`)

WPILib Kinematics Types

Type	Decoded Fields
`ChassisSpeeds`	`vx_mps`, `vy_mps`, `omega_radps`
`SwerveModuleState`	`speed_mps`, `angle_rad`, `angle_deg`
`SwerveModulePosition`	`distance_m`, `angle_rad`, `angle_deg`

Vision & Autonomous Types

Type	Decoded Fields
`TargetObservation`	`yaw_rad`, `yaw_deg`, `pitch_rad`, `pitch_deg`, `skew_rad`, `skew_deg`, `area`, `confidence`, `objectID`
`PoseObservation`	`timestamp`, `pose_x`, `pose_y`, `pose_z`, `pose_qw`, `pose_qx`, `pose_qy`, `pose_qz`, `ambiguity`, `tagCount`, `averageTagDistance`, `type`
`SwerveSample`	`timestamp`, `x`, `y`, `heading`, `heading_deg`, `vx`, `vy`, `omega`, `ax`, `ay`, `alpha`, `moduleForcesX[4]`, `moduleForcesY[4]`

Note: PoseObservation.type is decoded as an enum string: MEGATAG_1, MEGATAG_2, or PHOTONVISION.

Troubleshooting

MCP Server Shows "Failed"

Check Java version - Requires JDK 17 binary compatibility (JDK 21 is also fine):

/path/to/wpilib/2026/jdk/bin/java -version
# Should show: openjdk version "17.x.x" or "21.x.x"

Test manually:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | \
  java -jar wpilog-mcp-0.2.0-all.jar

Check config location:
- VS Code extension: .mcp.json in your project folder
- Claude Code CLI: ~/.claude/settings.json
- Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
Restart completely - Quit and relaunch (not just reload)

Log Files Show as Corrupted

Truncated logs (from robot power loss) are handled gracefully - the server recovers as much data as possible and marks the log as truncated.

Server Times Out

Usually means wrong Java version or incorrect path. Verify the JAR exists at the configured path.

Requirements

JDK 17+ (WPILib 2026 JDK recommended)
No other dependencies (WPILib libraries bundled)

WPILib JDK locations:

macOS: ~/wpilib/2026/jdk/bin/java
Windows: C:\Users\Public\wpilib\2026\jdk\bin\java.exe
Linux: ~/wpilib/2026/jdk/bin/java

Development

Project Structure

wpilog-mcp/
├── src/main/java/org/triplehelix/wpilogmcp/
│   ├── Main.java                 # Entry point
│   ├── log/
│   │   ├── LogManager.java       # WPILOG parsing & struct decoding
│   │   └── LogDirectory.java     # Log file discovery
│   ├── mcp/
│   │   ├── McpServer.java        # MCP protocol handling
│   │   └── JsonRpc.java          # JSON-RPC utilities
│   ├── tba/
│   │   ├── TbaClient.java        # TBA API client with caching
│   │   ├── TbaConfig.java        # TBA configuration management
│   │   └── TbaEnrichment.java    # Log enrichment with TBA data
│   └── tools/
│       ├── WpilogTools.java      # Tool registration
│       ├── CoreTools.java        # Log management tools (9)
│       ├── QueryTools.java       # Search & query tools (4)
│       ├── StatisticsTools.java  # Statistical analysis tools (6)
│       ├── RobotAnalysisTools.java # FRC analysis tools (7)
│       ├── FrcDomainTools.java   # Advanced FRC tools (6)
│       ├── ExportTools.java      # CSV/report export (2)
│       ├── TbaTools.java         # TBA integration (1)
│       └── ToolUtils.java        # Shared utilities
├── src/test/java/                # Test suite
├── build.gradle                  # Build configuration
├── README.md
└── TOOLS.md                      # Complete tool reference

Building

./gradlew build          # Full build with tests
./gradlew shadowJar      # Build fat JAR only
./gradlew test           # Run tests

Contributing

Report bugs - Open an issue with reproduction steps
Request features - Open an issue describing your use case
Submit PRs - Fork, make changes, add tests, submit

License

MIT License - see LICENSE

Acknowledgments

WPILib for the DataLog format
AdvantageKit for pioneering FRC replay logging
Anthropic for MCP and Claude
FRC Team 2363 Triple Helix

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
gradle/wrapper		gradle/wrapper
src		src
.gitignore		.gitignore
EXAMPLE.md		EXAMPLE.md
LICENSE		LICENSE
README.md		README.md
TOOLS.md		TOOLS.md
build.gradle		build.gradle
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
run-mcp.bat		run-mcp.bat
run-mcp.sh		run-mcp.sh
settings.gradle		settings.gradle

Folders and files

Latest commit

History

Repository files navigation

wpilog-mcp: Model Context Protocol (MCP) Server for WPILib Logs

What is MCP?

The Power of AI Reasoning

1. The Autonomous "Post-Match Pit Boss"

2. Strategic "Cycle Time" Optimization

3. Control Theory "Tuning Audit"

Quick Start

1. Build

2. Configure

3. Use

Table of Contents

Usage Examples

Browsing Logs

Basic Analysis

Robot Position

Threshold Events

Console Output

Swerve Analysis

AdvantageKit Replay

Multi-Log Analysis

Memory Management

Configuration Options

Command Line

The Blue Alliance Integration

Claude Desktop

Other MCP Clients

Available Tools

Supported Data Types

Primitive Types

WPILib Geometry Types

WPILib Kinematics Types

Vision & Autonomous Types

Troubleshooting

MCP Server Shows "Failed"

Log Files Show as Corrupted

Server Times Out

Requirements

Development

Project Structure

Building

Contributing

License

Acknowledgments

See Also

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages