MCP Server

SpikeLab includes an MCP (Model Context Protocol) server that exposes analysis tools for programmatic access by AI agents and other MCP clients. The server provides a workspace-centric interface to SpikeLab’s data loading, analysis, and export capabilities over the standard MCP stdio transport.

Starting the server

Run the MCP server as a Python module:

python -m spikelab.mcp_server

This starts the server on stdio transport (the default). MCP clients (such as Claude Desktop or other MCP-compatible tools) connect by launching this command as a subprocess and communicating over stdin/stdout.

Example configuration for an MCP client:

{
  "mcpServers": {
    "spikelab": {
      "command": "python",
      "args": ["-m", "spikelab.mcp_server"]
    }
  }
}

To use SSE (Server-Sent Events) transport instead, pass --transport sse:

python -m spikelab.mcp_server --transport sse --port 8080

SSE transport requires the sse optional dependency group (pip install spikelab[sse]).

The server requires the mcp Python package as a dependency.

Tool categories

The server registers over 90 tools organized into several categories:

Data loading tools

Load spike train data from various formats into the workspace. Each loader stores a SpikeData object in the workspace and returns the workspace ID, namespace, key, and a data summary.

  • load_from_hdf5_raster – HDF5 raster style

  • load_from_hdf5_ragged – HDF5 ragged (flat spike_times + index) style

  • load_from_hdf5_group – HDF5 group-per-unit style

  • load_from_hdf5_paired – HDF5 paired (idces + times) style

  • load_from_nwb – Neurodata Without Borders format

  • load_from_kilosort – KiloSort/Phy output folder

  • load_from_pickle – Pickle files (local or S3)

  • load_from_hdf5_thresholded – Raw HDF5 traces with threshold detection

  • load_from_ibl – International Brain Laboratory public data

Analysis tools

Run analysis operations on data already loaded into the workspace. Results are stored back into the workspace for subsequent use. Examples include:

  • compute_rates, compute_binned, compute_raster – basic firing statistics

  • compute_spike_time_tilings – pairwise spike time tiling coefficients

  • compute_pairwise_fr_corr, compute_pairwise_ccg – pairwise comparisons

  • create_rate_slice_stack, create_spike_slice_stack – event-aligned slicing

  • align_to_events – align data to stimulus or behavioral events

  • compute_rate_manifold – dimensionality reduction (PCA, UMAP, t-SNE)

  • fit_gplvm – Gaussian Process Latent Variable Model fitting

Export tools

Export data from the workspace to files:

  • export_to_hdf5 – HDF5 format (multiple styles)

  • export_to_nwb – NWB format

  • export_to_kilosort – KiloSort/Phy folder format

  • export_to_pickle – Pickle format (local or S3)

Workspace addressing

All MCP tools use a workspace-centric addressing model. Data items are identified by three coordinates:

  • workspace_id – identifies the workspace instance. When left empty on a loader call, a new workspace is created and its ID is returned.

  • namespace – a logical grouping within a workspace, typically one per recording or experimental session. When left empty on a loader call, the namespace is derived from the input file or folder name. If that namespace already exists, a numeric suffix (_1, _2, …) is appended.

  • key – identifies a specific data item within a namespace. For example, SpikeData is always stored at key "spikedata". Analysis results are stored at user-specified keys.

A typical workflow looks like this:

  1. Call a loader tool (e.g. load_from_hdf5_ragged) with an empty workspace_id. The server creates a workspace and returns its ID.

  2. Call analysis tools using the returned workspace_id and namespace, specifying output keys for each result.

  3. Call further analysis tools that build on previous results by referencing their keys.

  4. Call export tools to save results to files.

All tools return JSON-serializable dictionaries. Errors are returned as {"error": "...", "type": "..."} rather than raising exceptions, making the server safe for automated use.