MNE MCP Guard

Use this skill to make MNE MCP execution reliable, especially before expensive steps (ICA, time-frequency, source localization) and on unfamiliar data.

Workflow

Scientific dependencies are user-managed. Report the interpreter shown by mne_check_status. Distinguish missing packages from import-time binary/configuration errors. Never install packages inside mne_run_code or recreate an existing research environment. Missing optional libraries block only the relevant feature. After an authorized environment change, restart and check status again.

In PsyClaw, discover the mne server via psyclaw_mcp action=list before calling its tools. A successful setup check is not proof that an already-open session has reloaded. For missing tools or an unexpected interpreter, read the PsyClaw connection section in ../mne-analyst/references/environment.md; project configs override user configs.

1. Check capability first — mne_check_status. If MNE is missing, stop and say so; if

scikit-learn is missing, ICA is unavailable.

1. Inspect before processing — mne_get_info / mne_describe. Never guess channel names,

sampling rate, montage, or event codes.

1. Look before parameterizing — mne_plot_psd (read the PNG) before choosing filter cutoffs;

mne_plot_raw before choosing rejection thresholds.

1. Smoke-test heavy steps

• Before ICA: confirm data is high-pass filtered (~1 Hz) and montage is set.
• Before epoching: verify real event codes exist (mne_find_events /

mne_events_from_annotations) and that the epoch window fits the recording.

• Before TFR: confirm the epoch window is long enough for the lowest frequency.

1. Escalate gradually — get a minimal version working (one condition, default params), then add

options. Don't jump to a 60-component ICA or full source pipeline on the first try.

1. Read warnings, not just success — dropped epochs, rank deficiency, montage subset warnings,

and annotation notes change the validity of results.

Guardrails

• Units are SI (volts/tesla). A reject of 100 is 100 volts. 100 µV is 100e-6. This is the

most common silent error — verify any threshold's order of magnitude.

• Set a montage before topomaps, ICA component plots, or interpolation.
• High-pass before ICA (~1 Hz) or components will be unstable.
• Don't assume a file loads in one call — BrainVision/EEGLAB need sidecar files; point at the header.
• Timeout does not stop the worker. Check mne_check_status until idle, then inspect

objects before deciding on a retry. Never repeat an in-place step blindly; partial changes may already exist. Busy sessions reject code, reads and reset as well.

Decision tree

1. "no session object named ..."? → mne_session_info; load the data or fix the name.
2. Plot/interpolation error mentioning positions/montage? → mne_set_montage; check channel

names match the montage.

1. ICA error or weird components? → confirm sklearn present, high-pass applied, and

n_components ≤ data rank (lower it or use a 0.99 variance fraction).

1. TFR "wavelet longer than signal"? → wider epochs, higher fmin, or smaller n_cycles via

mne_compute_tfr (explicit frequencies and cycles).

1. All epochs dropped / empty evoked? → loosen reject_eeg, verify event codes, check the epoch

window against recording length.

1. Step times out? → check busy/idle status, inspect results after idle, then adjust future

timeouts or workload. A restart loses unsaved session data and needs an explicit decision.

References

• Read references/failure-patterns.md for concrete error→fix mappings.
• Use mne-analyst for the full workflow and pipeline conventions; this skill is specifically for

failure prevention and recovery.