MIDI Analyzer MCP Server

MIDI Analyzer MCP Server

A Model Context Protocol (MCP) server for analyzing MIDI SMF (Standard MIDI File) files. This server provides comprehensive tools for loading, parsing, and analyzing MIDI files.

Features

• MIDI File Loading: Load and parse MIDI SMF files
• File Summary: Get comprehensive information about MIDI files (format, PPQ, tempo, time signature, key signature, etc.)
• Track Analysis: List and analyze individual tracks with filtering capabilities
• Event Extraction: Extract and filter MIDI events with advanced filtering options
• Memory Management: Keep loaded files in memory for efficient repeated access

Available Tools

1. load_midi_file

Load and parse a MIDI SMF file from a specified path.

Parameters:

• filePath (string): Path to the MIDI file

Returns:

• fileId: Unique identifier for the loaded file
• filePath: Path to the loaded file
• format: MIDI format type (0, 1, or 2)
• trackCount: Number of tracks
• ppq: Pulses per quarter note
• totalEvents: Total number of events

2. get_midi_summary

Get comprehensive summary information about a MIDI file.

Parameters:

• fileId (string, optional): ID of loaded file
• filePath (string, optional): Path to MIDI file

Returns:

• Complete summary including format, PPQ, total ticks, track count, tempo info, time signatures, key signatures

3. get_tracks_list

Get list of tracks with optional filtering.

Parameters:

• fileId or filePath: File identifier
• channelFilter (number, optional): Filter by MIDI channel (0-15)
• programFilter (number, optional): Filter by program number (0-127)

Returns:

• Array of track information including names, channels, programs, event counts

4. get_track_details

Get detailed information about a specific track.

Parameters:

• fileId or filePath: File identifier
• trackIndex (number): Track index to analyze
• timeRange (object, optional): Filter events by time range
• eventTypeFilter (array, optional): Filter by event types
• valueFilter (object, optional): Filter by specific values

Returns:

• Track metadata and filtered events

5. get_midi_events

Extract MIDI events with comprehensive filtering.

Parameters:

• fileId or filePath: File identifier
• timeRange (object, optional): Time range filter
• eventTypeFilter (array, optional): Event type filter
• trackFilter (array, optional): Track filter
• valueFilter (object, optional): Value filter

Returns:

• Filtered array of MIDI events

Installation

Prerequisites

• Node.js (version 18 or higher)
• npm (comes with Node.js)

Adding to Claude Code

Method 1: Using npx (Recommended - No Local Installation Required)

Add the following configuration to your Claude Code settings file:

This method automatically downloads and runs the latest version from GitHub without requiring local installation.

Method 2: Local Installation (For Development or Offline Use)

1. Clone the repository:
   git clone https://github.com/sin5ddd/midi-analyzer-mcp.git cd midi-analyzer-mcp
2. Install dependencies:
   npm install
3. Build the project:
   npm run build
4. Configure Claude Code:

For Windows:

For Unix/Linux/macOS:

Configuration File Locations

Claude Code configuration files are located at:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Quick Setup with npx (Recommended)

1. Add to Claude Code configuration:
   { "mcpServers": { "midi-analyzer": { "command": "npx", "args": ["sin5ddd/midi-analyzer-mcp"] } } }
2. Restart Claude Code to load the new MCP server.
3. Test the installation by asking Claude Code:
   "Load the MIDI file at [path] and analyze its contents"

Local Development Setup

1. Clone and setup the repository:
   git clone https://github.com/sin5ddd/midi-analyzer-mcp.git cd midi-analyzer-mcp npm install npm run build
2. Add to Claude Code configuration:
   { "mcpServers": { "midi-analyzer": { "command": "node", "args": ["/path/to/midi-analyzer-mcp/dist/index.js"], "cwd": "/path/to/midi-analyzer-mcp" } } }

Development

Local Development

Build for Production

Run in Production

Troubleshooting

1. Installation Issues:
   • Ensure Node.js version 18+ is installed: node --version
   • Check npm version: npm --version
   • Try clearing npm cache: npm cache clean --force
2. Claude Code Integration:
   • Verify the path to dist/index.js is correct and absolute
   • Ensure the project has been built with npm run build
   • Check Claude Code logs for MCP server startup errors
   • Make sure Node.js is accessible from the command line
3. Runtime Issues:
   • Verify MIDI file paths are correct and accessible
   • Check file permissions for MIDI files
   • Ensure MIDI files are valid SMF format
4. Updates:For npx method: Updates are automatic - npx always downloads the latest version.For local installation:
   cd /path/to/midi-analyzer-mcp git pull origin main npm install npm run build
   Then restart Claude Code.

Event Types

The server recognizes the following MIDI event types:

• noteOn: Note on events
• noteOff: Note off events
• noteAftertouch: Note aftertouch
• controller: Control change
• programChange: Program change
• channelAftertouch: Channel aftertouch
• pitchBend: Pitch bend
• sysEx: System exclusive
• meta: Meta events (tempo, time signature, etc.)

Filtering Options

Time Range

Filter events by MIDI tick range:

Value Filter

Filter events by specific values:

Error Handling

The server provides detailed error messages for:

• File not found
• Invalid MIDI files
• Out of range track indexes
• Invalid parameters

License

MIT