{"id":49744040,"url":"https://github.com/trudenboy/ma-provider-mcp","last_synced_at":"2026-05-27T22:00:53.858Z","repository":{"id":356817271,"uuid":"1234112380","full_name":"trudenboy/ma-provider-mcp","owner":"trudenboy","description":"FastMCP server for Music Assistant — control MA from Claude Code, Codex, Cursor, and other AI agents","archived":false,"fork":false,"pushed_at":"2026-05-22T14:11:47.000Z","size":591,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2026-05-22T18:49:29.738Z","etag":null,"topics":["ai","ai-agents","chatgpt","claude-code","cline","codex","cursor","fastmcp","gemini","home-assistant","llm-tools","mcp","mcp-server","music-assistant","plugin-provider","python","vscode","zed"],"latest_commit_sha":null,"homepage":"https://trudenboy.github.io/ma-provider-mcp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trudenboy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-09T19:07:44.000Z","updated_at":"2026-05-22T14:10:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/trudenboy/ma-provider-mcp","commit_stats":null,"previous_names":["trudenboy/ma-provider-mcp"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/trudenboy/ma-provider-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trudenboy%2Fma-provider-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trudenboy%2Fma-provider-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trudenboy%2Fma-provider-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trudenboy%2Fma-provider-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trudenboy","download_url":"https://codeload.github.com/trudenboy/ma-provider-mcp/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trudenboy%2Fma-provider-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33585203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","chatgpt","claude-code","cline","codex","cursor","fastmcp","gemini","home-assistant","llm-tools","mcp","mcp-server","music-assistant","plugin-provider","python","vscode","zed"],"created_at":"2026-05-10T00:10:43.612Z","updated_at":"2026-05-27T22:00:53.849Z","avatar_url":"https://github.com/trudenboy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ma-provider-mcp\n\n\n\u003c!-- \u003e\u003e\u003e ma-provider-tools sync (readme header) — DO NOT EDIT \u003e\u003e\u003e --\u003e\n[![CI](https://github.com/trudenboy/ma-provider-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/trudenboy/ma-provider-mcp/actions/workflows/test.yml)\n[![Release](https://img.shields.io/github/v/release/trudenboy/ma-provider-mcp?display_name=tag)](https://github.com/trudenboy/ma-provider-mcp/releases/latest)\n[![License](https://img.shields.io/github/license/trudenboy/ma-provider-mcp)](LICENSE)\n[![Music Assistant](https://img.shields.io/badge/Music%20Assistant-9070B8?logo=python\u0026logoColor=white)](https://www.music-assistant.io/)[![stable](https://img.shields.io/endpoint?url=https%3A%2F%2Ftrudenboy.github.io%2Fma-provider-tools%2Fbadges%2Ffastmcp_server-stable.json)](https://github.com/music-assistant/server/releases/latest)[![beta](https://img.shields.io/endpoint?url=https%3A%2F%2Ftrudenboy.github.io%2Fma-provider-tools%2Fbadges%2Ffastmcp_server-beta.json)](https://github.com/music-assistant/server/releases?q=prerelease)\n[![Stars](https://img.shields.io/github/stars/trudenboy/ma-provider-mcp?style=flat\u0026logo=github)](https://github.com/trudenboy/ma-provider-mcp/stargazers)\n\n**📖 [Documentation](https://trudenboy.github.io/ma-provider-mcp/)** · **🔄 [Changelog](CHANGELOG.md)** · **🐛 [Issues](https://github.com/trudenboy/ma-provider-mcp/issues)** · **💬 [Discussions](https://github.com/trudenboy/ma-provider-mcp/discussions)**\n\u003c!-- \u003c\u003c\u003c ma-provider-tools sync (readme header) \u003c\u003c\u003c --\u003e\n\n**MCP Server** plugin provider for [Music Assistant](https://github.com/music-assistant/server).\n\nExposes MA's library, queue, playback, players, and metadata controllers as a\n[Model Context Protocol](https://modelcontextprotocol.io/) server, accessible to\nClaude Code, Codex, and any other MCP-aware LLM client.\n\n## Highlights\n\n- Built on **PrefectHQ FastMCP v3** — no homebrew SDK glue.\n- **No core MA changes required.** Authentication delegates to\n  `mass.webserver.auth.authenticate_with_token` (handles both JWT and legacy tokens).\n- **16-permission tag-based access control** (query / control / edit / delete × 4 categories);\n  defaults: reads on, all mutations off.\n- **Mounted into MA's existing webserver** at `/mcp/v1` — reuses TLS, reverse proxy,\n  and Home Assistant ingress out of the box. No second port, no extra firewall rule.\n- 8 namespaced sub-servers, exposing tools as `library_search_tracks`,\n  `queue_get_active_queue`, `playback_play_media`, etc.\n\n## Usage\n\n### Quick connect (recommended)\n\nAfter enabling the plugin in MA settings, click **Open Connect Wizard**\nin the provider's config panel. Pick your AI client — the wizard mints a\nper-client token (`MCP — \u003cClient\u003e`, revocable individually under\nProfile → Long-lived access tokens) and shows the ready-to-paste snippet.\nCursor users get an extra **Add to Cursor** one-click deeplink. Supports\nClaude Desktop, Claude Code, Cursor, Windsurf, VSCode, ChatGPT\nConnectors, Codex CLI, Gemini CLI, Cline, and Zed.\n\n### Manual\n\n```bash\nTOKEN=\"\u003cmint a token in MA Profile → Long-lived access tokens\u003e\"\n\n# Probe streamable HTTP transport\ncurl -sS -H \"Authorization: Bearer $TOKEN\" \\\n     -H \"Accept: text/event-stream\" \\\n     http://localhost:8095/mcp/v1\n\n# Connect Claude Code\nclaude mcp add ma --transport http \\\n  --url http://localhost:8095/mcp/v1 \\\n  --header \"Authorization: Bearer $TOKEN\"\n```\n\n## Permissions\n\nThe provider config exposes 16 permission booleans, grouped by category:\n\n| Category   | Verbs                                                                |\n|------------|----------------------------------------------------------------------|\n| Query      | library, queue, players, metadata                                    |\n| Control    | playback, volume, players, media (announcements)                     |\n| Edit       | library (add), queue (move/save), playlists (create/add/reorder), favorites (add) |\n| Delete     | library (remove), queue (clear), playlists (delete), favorites (remove) |\n\nEach maps to a tag (`query:library`, `control:playback`, …). A custom\n`TagFilterMiddleware` filters `tools/list` / `resources/list` / `prompts/list`\n**and** blocks direct invocation of disabled components — so a client that\ncached a tool name from an earlier permission set cannot bypass the filter.\n\n## Spec compliance (MCP 2025-06-18 / draft)\n\n- **Streamable HTTP transport** with mandatory `Origin` validation\n  (DNS-rebinding mitigation). Allowlist auto-built from `mass.webserver`;\n  add reverse-proxy hosts via `extra_allowed_origins` (CSV).\n- **OAuth 2.0 Protected Resource Metadata** (RFC 9728) at\n  `/.well-known/oauth-protected-resource[/mcp/v1]`, plus `resource_metadata`\n  in `WWW-Authenticate` 401 responses.\n- **Resource Indicator support** (RFC 8707): `AccessToken.resource` is set,\n  optional `enforce_audience` config rejects tokens whose `aud` ≠ canonical\n  URI (soft mode by default — logs warning until MA issues audience-bound JWTs).\n- **Tool annotations** (`title`, `readOnly`/`destructive`/`idempotent`/`openWorld` hints).\n- **Elicitation** for destructive operations.\n- **Per-tool timeouts** so a stuck provider doesn't tie up an MCP session.\n\n## Development\n\n```bash\nuv sync --all-extras\nuv run pytest\nuv run ruff check provider tests\nuv run mypy provider\n```\n\n## License\n\n[Apache-2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrudenboy%2Fma-provider-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrudenboy%2Fma-provider-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrudenboy%2Fma-provider-mcp/lists"}