mcp-kodi

Overview Schema Source Related Servers Discussions Admin

searchmedia

Instructions

Find playable files by name: music/tv-show/movie, drilled to leaf files with paging (limit/offset) and a total count. For music, title means the ALBUM name; match a song by its own title with the song arg ("play Hey Jude" needs no artist). Find a tv episode by its own name with the episodetitle arg. Movie and tv-show queries can also filter by actor/director. Finds media items only — for people lookups (bands, artists, who is in the library) use contributors. Returns { "type", "total", "returned", "offset", "truncated", "rows": [ { "file", "id", "label", "title", … } ] }.

Input Schema

Name	Required	Description
`song`	No	Music only: song title (substring, case-insensitive). Matches songs by their OWN name library-wide — the way to find a track without its album; narrow with artist/title(album)/number. Rows carry no resolved container.
`type`	Yes	Media kind to search: music \| tv-show \| movie.
`actor`	No	movie/tv-show only: cast-member name (substring, case-insensitive). For tv-show it matches episode cast, which includes guest stars; combinable with title.
`count`	No	When true, return only the total match count (zero rows) — a cheap count.
`limit`	No	Max leaf rows to return (default 50, max 500). Page with offset.
`title`	No	Container/title to match (substring, case-insensitive): album for music (a song's own title is the separate `song` arg), show for tv-show, the movie title for movie. tv-show needs title, actor or director; without title the person is matched library-wide and rows carry showtitle. Music without artist resolves the album library-wide.
`artist`	No	Music only: performer name (substring, case-insensitive). Resolves the artist; music needs artist, title or song.
`number`	No	Position within the container: track number (music) or episode number (tv-show) — for an episode's title use episodetitle.
`offset`	No	Number of leaf rows to skip — paginate together with limit.
`season`	No	tv-show only: season number to narrow the episodes.
`director`	No	movie/tv-show only: director name (substring, case-insensitive). For tv-show it matches per-episode directors; combinable with title.
`instance`	No	Target Kodi instance. Omitted uses the default ("(null)").
`episodetitle`	No	tv-show only: an episode's OWN title (substring, case-insensitive) — the way to find an episode by name. Matched library-wide (rows carry showtitle) unless a show title also narrows it. This is the title, NOT the episode number (use number for that).

Output Schema

Name	Required	Description
`rows`	Yes	The matching leaf rows, paged.
`type`	Yes	The searched media type, echoed back.
`total`	Yes	Full match count, before any paging.
`offset`	Yes	Rows skipped before this page.
`resolved`	No	The container the query resolved to — { "artist"?\|"show"?, "artistid"\|"tvshowid" } — when it drilled through one.
`returned`	Yes	Rows in this page.
`truncated`	Yes	Whether matches remain beyond this page.
`approximate`	No	Present (true) when total/paging are app-side estimates (a substring title matched several albums).

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 13, 2026

changedInput schema / properties / artist / description

Previous value: -"Music only: performer name (substring, case-insensitive). Resolves the artist; music needs artist or title."New value: +"Music only: performer name (substring, case-insensitive). Resolves the artist; music needs artist, title or song."

addedInput schema / properties / episodetitle

Added value: +{
+  "description": "tv-show only: an episode's OWN title (substring, case-insensitive) — the way to find an episode by name. Matched library-wide (rows carry showtitle) unless a show title also narrows it. This is the title, NOT the episode number (use number for that).",
+  "type": "string"
+}

changedInput schema / properties / number / description

Previous value: -"Position within the container: track number (music) or episode number (tv-show)."New value: +"Position within the container: track number (music) or episode number (tv-show) — for an episode's title use episodetitle."

addedInput schema / properties / song

Added value: +{
+  "description": "Music only: song title (substring, case-insensitive). Matches songs by their OWN name library-wide — the way to find a track without its album; narrow with artist/title(album)/number. Rows carry no resolved container.",
+  "type": "string"
+}

changedInput schema / properties / title / description

Previous value: -"Container/title to match (substring, case-insensitive): album for music, show for tv-show, the movie title for movie. tv-show needs title, actor or director; without title the person is matched library-wide and rows carry showtitle. Music without artist resolves the album library-wide."New value: +"Container/title to match (substring, case-insensitive): album for music (a song's own title is the separate `song` arg), show for tv-show, the movie title for movie. tv-show needs title, actor or director; without title the person is matched library-wide and rows carry showtitle. Music without artist resolves the album library-wide."

First observedv0.1.0Jun 14, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden and does so well: it discloses paging via limit/offset, a total count, truncation, the full return envelope, and that song-matched rows carry no resolved container while library-wide person matches carry showtitle. It doesn't state read-only-ness explicitly or discuss result ordering, but the read semantics of 'search' are effectively unambiguous.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first clause, followed by parameter routing and the return shape. It is dense but appropriately sized for a 13-parameter tool; the only waste is that the `episodetitle` and `song` explanations restate the schema param descriptions nearly verbatim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-param search with an output schema, the description covers every meaningful axis: media kinds, paging, the container-vs-item distinction, the sibling escape hatch, and cross-parameter combinations. The return-shape sketch is technically redundant given the output schema, but nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns above it by disambiguating the two most confusable parameters ('For music, title means the ALBUM name; match a song by its own title with the `song` arg') and by mapping actor/director to cast vs per-episode matching. Support is largely duplicative of the schema, which keeps it at 4 rather than 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Find playable files by name: music/tv-show/movie'), names the leaf-file granularity, paging and total count. It also explicitly carves out the sibling boundary: 'Finds media items only — for people lookups ... use `contributors`.' An agent can distinguish this from every sibling without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use routing: `song` for a track by its own title, `title` for the album/show/movie container, `episodetitle` for an episode by name, and `contributors` for people. The 'play Hey Jude needs no artist' example resolves a real ambiguity an agent would otherwise get wrong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.