Skip to content
Back to search

id3mcp

`id3mcp` is a Go MCP (Model Context Protocol) server for reading and editing ID3 tags in MP3 files. It works over stdio and can be used with any MCP-compatible agent or client, not just a specific one.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ip75--id3mcp/badge.svg)](/listings/ip75--id3mcp)

HTML

<a href="/listings/ip75--id3mcp"><img src="/api/listings/ip75--id3mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the latest tagged release with Go:

go install github.com/ip75/id3mcp@latest

Or install a specific version:

go install github.com/ip75/id3mcp@v0.1.0

The `id3mcp` binary will be placed in `$GOBIN` or `$HOME/go/bin` (Windows: `%USERPROFILE%\go\bin`).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 203 lines
  1. # id3mcp
  2. `id3mcp` is a Go MCP (Model Context Protocol) server for reading and editing ID3 tags in MP3 files. It works over stdio and can be used with any MCP-compatible agent or client, not just a specific one.
  3. The server focuses on safe, local tag editing: it exposes MCP tools for listing files, reading tags, setting text fields, adding/replacing front covers, and extracting covers. All file access is restricted to a configured root directory.
  4. ## Features
  5. - MCP stdio server (`id3mcp` binary)
  6. - ID3v2 tag reading and writing for `.mp3` files
  7. - Text tag editing: title, artist, album, album artist, genre, year, track, disc, composer, comment
  8. - Cover management: set front cover from `.jpg/.jpeg/.png`, extract existing cover
  9. - Directory listing with optional recursion (`id3_list`, `recursive=true`)
  10. - Preview mode for mutating operations (`confirm=false`)
  11. - Backup before first write (`<file>.mp3.id3mcp.bak`)
  12. - Jail/root protection: paths must stay inside `ID3MCP_ROOT` (including symlink resolution)
  13. - Cyrillic/Unicode handling with ID3v2 version-aware encoding:
  14. - ID3v2.3 writes UTF-16
  15. - ID3v2.4 writes UTF-8
  16. - existing v2.4 files stay v2.4 unless explicitly forced
  17. ## Requirements
  18. - Go 1.27+ (as declared in `go.mod`)
  19. - Node.js (for the MCP integration test script)
  20. - `make` (optional, for convenience targets)
  21. ## Install
  22. Install the latest tagged release with Go:
  23. ```bash
  24. go install github.com/ip75/id3mcp@latest
  25. ```
  26. Or install a specific version:
  27. ```bash
  28. go install github.com/ip75/id3mcp@v0.1.0
  29. ```
  30. The `id3mcp` binary will be placed in `$GOBIN` or `$HOME/go/bin` (Windows: `%USERPROFILE%\go\bin`).
  31. ## Build from source
  32. ```bash
  33. git clone https://github.com/ip75/id3mcp.git
  34. cd id3mcp
  35. go build -o id3mcp.exe .
  36. ```
  37. Cross-build targets from `Makefile`:
  38. ```bash
  39. make freebsd
  40. make linux
  41. make windows
  42. make all
  43. ```
  44. ## Run as MCP server
  45. `id3mcp` communicates over MCP stdio. Set `ID3MCP_ROOT` to the directory containing MP3 files the server is allowed to access.
  46. If installed via `go install`, make sure your Go bin directory is on `PATH`, or use the full path to the installed binary.
  47. Example (PowerShell):
  48. ```powershell
  49. $env:ID3MCP_ROOT = "C:\music\work"
  50. id3mcp
  51. # or, from a local build:
  52. .\id3mcp.exe
  53. ```
  54. Example (bash):
  55. ```bash
  56. export ID3MCP_ROOT=/path/to/music/work
  57. id3mcp
  58. # or, from a local build:
  59. ./id3mcp
  60. ```
  61. The process expects an MCP client on stdin/stdout. Logs/errors go to stderr.
  62. ## MCP client configuration example
  63. Configure your MCP client to launch the binary with `ID3MCP_ROOT` set. The exact config format depends on the client; the important parts are command, args, and environment.
  64. Generic JSON example:
  65. ```json
  66. {
  67. "mcpServers": {
  68. "id3mcp": {
  69. "command": "C:\\path\\to\\id3mcp.exe",
  70. "args": [],
  71. "env": {
  72. "ID3MCP_ROOT": "C:\\path\\to\\music\\work"
  73. }
  74. }
  75. }
  76. }
  77. ```
  78. Crush (`crushrc`) example:
  79. ```bash
  80. mcp add id3mcp \
  81. --command "C:\\Users\\IP\\go\\bin\\id3mcp.exe" \
  82. --env ID3MCP_ROOT="C:\\music\\work"
  83. ```
  84. If you built from source or placed the binary elsewhere, use that path in `--command`. On Linux/macOS, use the corresponding binary path, e.g. `~/go/bin/id3mcp`.
  85. ## Agent skill
  86. The repo includes an agent skill at [`skills/id3mcp/SKILL.md`](skills/id3mcp/SKILL.md). It teaches an agent when and how to use the `id3mcp` MCP tools safely (preview before writes, batch limits, root jail, ID3 version behavior).
  87. Install/copy it into your skills directory, for example:
  88. ```bash
  89. # Example: copy into a local skills directory
  90. cp -r skills/id3mcp ~/.agents/skills/id3mcp
  91. ```
  92. ## Supported MCP tools
  93. | Tool | Description | Mutates files |
  94. |---|---|---|
  95. | `id3_list` | List `.mp3` files in a directory inside `ID3MCP_ROOT`. Set `recursive=true` to include subdirectories. | No |
  96. | `id3_read` | Read tags and cover summary (no image bytes). | No |
  97. | `id3_set` | Edit text tags in a batch. Use `confirm=false` for preview, `confirm=true` to write. | Yes |
  98. | `id3_set_cover` | Set front cover from `.jpg/.jpeg/.png` inside the working root. | Yes |
  99. | `id3_extract_cover` | Extract cover to a file inside the working root. | Yes (writes extracted image file) |
  100. ### Notes on behavior
  101. - `id3_set` and `id3_set_cover` require `confirm=false` for a safe preview before writing.
  102. - Empty string clears a text field in `id3_set`.
  103. - `track` and `disc` accept values like `"3"` or `"3/12"`.
  104. - New files/default writes use ID3v2.3 with UTF-16. ID3v2.4 files remain UTF-8. Use `force_version=4` to write UTF-8/ID3v2.4 explicitly.
  105. - ID3v1 is stripped on write by default (`ID3MCP_STRIP_V1=0` keeps it).
  106. - `id3_list` can recurse with `recursive=true`; it returns up to 200 files and sets `truncated=true` if more exist. Apply `id3_set`/`id3_set_cover` in batches (`ID3MCP_MAX_FILES`).
  107. ## Configuration
  108. Environment variables:
  109. | Variable | Default | Description |
  110. |---|---:|---|
  111. | `ID3MCP_ROOT` | required | Root directory jail. All file paths must resolve inside it. |
  112. | `ID3MCP_MAX_FILES` | `25` | Max files per call (min 1, max 100). |
  113. | `ID3MCP_MAX_BYTES` | `104857600` (100 MiB) | Max MP3 file size. |
  114. | `ID3MCP_MAX_IMAGE` | `2097152` (2 MiB) | Max cover image size. |
  115. | `ID3MCP_DEFAULT_VERSION` | `3` | Default ID3v2 version for new tags (`3` or `4`). |
  116. | `ID3MCP_STRIP_V1` | `true` | Strip ID3v1 on write. Set `0/false/no/off` to keep. |
  117. ## Safety model
  118. - All paths are resolved and checked against `ID3MCP_ROOT`; symlink escapes are rejected.
  119. - Only regular files with expected extensions are accepted.
  120. - Mutating tag tools support preview (`confirm=false`).
  121. - A backup file (`*.id3mcp.bak`) is created before the first write and not overwritten by later writes.
  122. - Do not point `ID3MCP_ROOT` at a large archive. Work on a copied batch.
  123. ## Development
  124. Run Go tests:
  125. ```bash
  126. go test ./...
  127. ```
  128. Run MCP integration tests (builds a test binary and exercises all MCP tools over stdio):
  129. ```bash
  130. make test-integration
  131. ```
  132. Format/vet:
  133. ```bash
  134. gofmt -l .
  135. go vet ./...
  136. ```
  137. ## Project layout
  138. - `main.go` - CLI/bootstrap, config loading, MCP stdio server startup
  139. - `tools.go` - MCP tool registration and handlers
  140. - `tags.go` - ID3 read/write/cover logic
  141. - `jail.go` - path jail and file safety checks
  142. - `tags_test.go` - Go unit tests
  143. - `test_mcp_integration.mjs` - MCP stdio integration test for all tools
  144. - `Makefile` - build and integration-test recipes
  145. ## Limitations / non-goals
  146. - No audio transcoding or audio content modification.
  147. - No archive/library management features; intended for controlled batch edits in a working directory.
  148. - The project is not a general-purpose tagger UI; it is an MCP server for agents/clients.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.