Soundiiz MCP server
Commit Oct 30, 2026Lets an AI assistant inspect Soundiiz sync jobs and SmartLinks, trigger music service syncs, and manage published links.
Also known as BASIC-BIT/soundiiz-mcp
- Stars
- 1
- Tools
- 23
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 30, 2026
- License
- MIT
What is Soundiiz MCP?
Soundiiz lets an AI assistant inspect Soundiiz sync jobs and SmartLinks, trigger music service syncs, and manage published links. It exposes 23 tools, such as soundiiz_me, soundiiz_auth_status, soundiiz_syncs_list.
Summary generated from the project's README
About Soundiiz MCP server
Managing music streaming synchronization and SmartLinks is what soundiiz-mcp enables for users of AI clients like Claude Desktop or OpenCode. This server connects your assistant to the Soundiiz User API, allowing it to inspect sync jobs, monitor SmartLink status, and manage published links across various streaming services. It is designed for users with a Soundiiz Creator plan who want to automate or query their music data through a conversational interface.
Setup requires a Soundiiz API key, which can be stored locally in an environment variable, a file, or the OS keychain. The server provides curated tools for common workflows, such as triggering a sync or listing SmartLinks, alongside auto-generated tools for more granular API operations. To prevent accidental data loss, destructive actions like deleting a sync or a SmartLink use a two-step confirmation flow requiring a specific ID before execution. You can also restrict write access to specific IDs using allowlists or disable all write operations entirely via configuration.
What you can do with it
- 1Monitor music sync statusAsk your assistant to summarize which music sync jobs succeeded or failed and identify the involved platforms.
- 2Manually trigger scheduled syncsInstruct the AI to run a specific music synchronization job immediately rather than waiting for its next scheduled time.
- 3Manage SmartLink assetsRequest a list of all your published SmartLinks and their associated shortcodes to keep track of your links.
- 4Clean up old linksHave the assistant find and remove stale or draft SmartLinks from your account.
Written from the project's README. Every use case is checked against a quote from it.
How to install Soundiiz MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Soundiiz MCP in Claude Code
$ claude mcp add soundiiz-mcp -- npx -y soundiiz-mcpInstall Soundiiz MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"soundiiz-mcp": {
"command": "npx",
"args": [
"-y",
"soundiiz-mcp"
]
}
}
}Install Soundiiz MCP in VS Code
.vscode/mcp.json
{
"servers": {
"soundiiz-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"soundiiz-mcp"
]
}
}
}Install Soundiiz MCP in VS Code CLI
$ code --add-mcp '{"name":"soundiiz-mcp","type":"stdio","command":"npx","args":["-y","soundiiz-mcp"]}'Install Soundiiz MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"soundiiz-mcp": {
"command": "npx",
"args": [
"-y",
"soundiiz-mcp"
]
}
}
}Install Soundiiz MCP in Codex
$ codex mcp add soundiiz-mcp -- npx -y soundiiz-mcpInstall Soundiiz MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.soundiiz-mcp] command = "npx" args = ["-y", "soundiiz-mcp"]
Install Soundiiz MCP in Gemini CLI
$ gemini mcp add -s user soundiiz-mcp npx -- -y soundiiz-mcpInstall Soundiiz MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"soundiiz-mcp": {
"command": "npx",
"args": [
"-y",
"soundiiz-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for soundiiz-mcp 0.1.0 in an isolated container with no network and no keys. It answered and listed 23 tools.
Soundiiz MCP tools 23
Read from the server with tools/listsoundiiz_meGet the current authenticated Soundiiz user (id, username, email).
soundiiz_auth_statusCheck whether a Soundiiz API key is loaded and authenticates against /v1/me. Local-only call.
soundiiz_syncs_listList Soundiiz syncs as compact rows. Auto-paginates by default; pass paginated=true for a single page.
soundiiz_sync_getGet a single Soundiiz sync by id, including lastExecutionResult.
soundiiz_syncs_overviewCounts and shortlists across all syncs: by status, by frequency, by source/destination platform pair, plus dueSoon and recentFailures.
soundiiz_syncs_dueReturn syncs scheduled to run within the given window (default 24 hours).
soundiiz_sync_triggerTrigger execution of a Soundiiz sync. Returns a confirmId on the first call; re-call with the same args plus that confirmId to execute (skip via writes.confirmDestructive=false).
soundiiz_sync_deleteDelete a Soundiiz sync. Returns a confirmId on the first call; re-call with the same args plus that confirmId to execute (skip via writes.confirmDestructive=false).
soundiiz_smartlinks_listList Soundiiz SmartLinks as compact rows. Auto-paginates by default; pass paginated=true for one page.
soundiiz_smartlink_getGet a single Soundiiz SmartLink by id, including all per-platform links.
soundiiz_smartlinks_overviewCounts across all SmartLinks: by status, by category, by platform across all link members; plus most-recently-updated.
soundiiz_smartlink_deleteDelete a Soundiiz SmartLink. Returns a confirmId on the first call; re-call with the same args plus that confirmId to execute (skip via writes.confirmDestructive=false).
Show all 23 toolsShow fewer tools
soundiiz_cache_invalidateInvalidate MCP-local cached responses. Defaults to scope=all.
soundiiz_auth_setSet a Soundiiz API key for the current session. With keyStore=file or keychain, also persists locally. With keyStore=env, in-memory only. Always local; never transmits the key anywhere except to the Soundiiz API.
soundiiz_auth_clearClear the in-memory Soundiiz API key. With keyStore=file or keychain, also removes the persisted copy.
soundiiz_read_get_soundiiz_openapi_v1_merest_getme[User] Get detailed profile information about the current user.
soundiiz_read_get_soundiiz_openapi_v1_merest_getmesyncs[Syncs] Retrieves a paginated list of syncs owned by the authenticated user. This endpoint supports pagination via offset and limit query parameters to control the number of items returned.
soundiiz_read_get_soundiiz_openapi_v1_merest_getmesyncsdetails[Syncs] Retrieves details of a sync owned by the authenticated user identified by its Soundiiz ID.
soundiiz_write_delete_soundiiz_openapi_v1_merest_getmesyncsdelete[Syncs] Delete a user-owned synchronization identified by its Soundiiz ID. This endpoint delete the sync and returns a confirmation or failure status.
soundiiz_write_post_soundiiz_openapi_v1_merest_getmesyncsexecute[Syncs] Triggers the execution of a user-owned synchronization process identified by its Soundiiz ID. This endpoint initiates the sync and returns a confirmation or processing status.
soundiiz_read_get_soundiiz_openapi_v1_merest_getmesmartlinks[Smartlinks] Retrieves a paginated list of smartlinks owned by the authenticated user. This endpoint supports pagination via offset and limit query parameters to control the number of items returned.
soundiiz_read_get_soundiiz_openapi_v1_merest_getmesmartlinksdetails[Smartlinks] Retrieves details of a smartlink owned by the authenticated user identified by its Soundiiz ID.
soundiiz_write_delete_soundiiz_openapi_v1_merest_getmesmartlinksdelete[Smartlinks] Delete a user-owned smartlink identified by its Soundiiz ID. This endpoint delete the smartlink and returns a confirmation or failure status.
Configuration
SOUNDIIZ_API_KEYSOUNDIIZ_MCP_USER_AGENT
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablebasic-bit/soundiiz-mcp is public and reachablegithub.com/basic-bit/soundiiz-mcp ↗Pass
- Package names this repository as its sourcesoundiiz-mcp names basic-bit/soundiiz-mcp as sourcenpmjs.com/package/soundiiz-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-30github.com/basic-bit/soundiiz-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from soundiiz-mcpPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model1 tool description and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSoundiiz MCP
An MCP server for Soundiiz. Lets your AI assistant inspect your sync jobs and SmartLinks across streaming services, trigger syncs, and clean up stale links.
Built for Claude Desktop, OpenCode, and any other Model Context Protocol client.
Your API key stays on your machine. Curated tools on top of the Soundiiz User API so agents don't have to paginate through raw endpoints.
This project is unofficial and is not affiliated with Soundiiz.
Status
v0.1.0 — early. The Soundiiz User API is itself in BETA, so the surface this server wraps may shift. The 25-test mock suite exercises every curated tool, but the maintainer hasn't run it against a real Creator-plan account in the wild — if you're an early adopter, please try npm run smoke:live and file an issue if anything breaks.
What You Can Ask
- Show me all my Soundiiz syncs and which ones are due to run next.
- Summarize sync status: how many succeeded, how many failed, which platforms are involved.
- Which syncs failed recently, and why?
- Trigger sync #42 to run now.
- List all my published SmartLinks and their shortcodes.
- Show details for SmartLink "abc123": fallback URL, per-platform links, status.
- Delete this stale draft SmartLink.
Writes and confirmations
The Soundiiz API exposes three write operations:
- Trigger sync — non-destructive. The sync was already configured by you and runs on a schedule; triggering early just runs it now. Executes in one call.
- Delete sync and Delete SmartLink — destructive. Two-step confirm flow:
- The first call returns a
confirmIdand a recap of what would happen. - Re-call the same tool with the same args plus that
confirmIdto execute. The token is single-use and bound to the tool name + arg hash.
- The first call returns a
Knobs:
writes.confirmDestructive = false— skip the confirm step on deletes (one-call writes).writes.allow = false(orSOUNDIIZ_MCP_ALLOW_WRITES=false) — disable writes entirely.syncs.allowlist/smartlinks.allowlist— restrict writes to specific IDs.
Auth and storage
Your API key is read from SOUNDIIZ_API_KEY, a local file, or the OS keychain (via keytar). It never leaves your machine except in Authorization: Bearer headers to api.soundiiz.com.
Logs go to stderr so stdout stays reserved for MCP protocol messages. Live smoke checks and LLM evals are opt-in and read gitignored fixture files.
Quick Start
Requirements:
- Node.js 22 or newer.
- A Soundiiz account on the Creator plan. The Soundiiz User API is currently in BETA and gated to Creator subscribers.
- An MCP client such as Claude Desktop, OpenCode, or another MCP-compatible host.
Generate your personal API key at soundiiz.com/webapp/settings/api.
Install from source:
git clone https://github.com/BASIC-BIT/soundiiz-mcp.git
cd soundiiz-mcp
npm install
npm run build
MCP Client Config
Use the built server for day-to-day use. Replace the path with your local checkout.
{
"mcpServers": {
"soundiiz": {
"command": "node",
"args": ["<ABS_PATH_TO_REPO>/dist/bin/cli.js"],
"env": {
"SOUNDIIZ_API_KEY": "<YOUR_KEY>",
"SOUNDIIZ_MCP_USER_AGENT": "your-name (email@example.com)"
}
}
}
}
For active development, point at the TypeScript entrypoint instead:
{
"mcpServers": {
"soundiiz-dev": {
"command": "npx",
"args": ["tsx", "<ABS_PATH_TO_REPO>/src/index.ts"],
"env": {
"SOUNDIIZ_API_KEY": "<YOUR_KEY>",
"SOUNDIIZ_MCP_USER_AGENT": "your-name (email@example.com)"
}
}
}
}
Configuration
Defaults live in src/config/defaults.json. To override them, create a JSON config file and point to it with SOUNDIIZ_MCP_CONFIG_FILE.
Example soundiiz-mcp.config.json:
{
"api": {
"baseUrl": "https://api.soundiiz.com",
"userAgent": "your-name (email@example.com)"
},
"auth": { "keyStore": "env" },
"writes": { "allow": false, "confirmDestructive": true, "confirmTtlMs": 120000 },
"syncs": { "allowlist": [] },
"smartlinks": { "allowlist": [] },
"rateLimit": { "perMinute": 60 },
"cache": { "enabled": true }
}
Environment variables override the config file when set.
Common environment variables:
SOUNDIIZ_MCP_CONFIG_FILE: path to a JSON config file.SOUNDIIZ_API_KEY: your personal Soundiiz User API key (Bearer token).SOUNDIIZ_MCP_USER_AGENT: descriptive user agent. Include contact info when possible.SOUNDIIZ_MCP_API_BASE: override the API base URL. Defaults tohttps://api.soundiiz.com.SOUNDIIZ_MCP_LOG_LEVEL:debug,info,warn, orerror.SOUNDIIZ_MCP_KEY_STORE:env,file, orkeychain.SOUNDIIZ_MCP_KEY_FILE: file path whenSOUNDIIZ_MCP_KEY_STORE=file.SOUNDIIZ_MCP_ALLOW_WRITES: enable non-GET operations.SOUNDIIZ_MCP_CONFIRM_DESTRUCTIVE: require a confirmation token for DELETE / trigger.SOUNDIIZ_MCP_SYNC_ALLOWLIST: comma-separated list of sync IDs permitted for write actions.SOUNDIIZ_MCP_SMARTLINK_ALLOWLIST: comma-separated list of smartlink IDs permitted for write actions.SOUNDIIZ_MCP_ENABLE_RAW_CALL: enable the rawsoundiiz_calltool. Disabled by default.SOUNDIIZ_MCP_DISABLE_GENERATED_READ_TOOLS: disable auto-generated read tools.SOUNDIIZ_MCP_DISABLE_GENERATED_WRITE_TOOLS: disable auto-generated write tools.
Tool Surface
Soundiiz MCP exposes three layers (mirroring the vrchat-mcp pattern):
- Curated tools for common agent workflows:
soundiiz_me,soundiiz_syncs_list,soundiiz_syncs_overview,soundiiz_syncs_due,soundiiz_sync_get,soundiiz_smartlinks_list,soundiiz_smartlinks_overview,soundiiz_smartlink_get,soundiiz_sync_trigger,soundiiz_sync_delete,soundiiz_smartlink_delete. - Auto-generated read tools named
soundiiz_read_<operationId>for GET operations from the Soundiiz OpenAPI spec. - Auto-generated write tools named
soundiiz_write_<operationId>for non-GET operations.
Local-only tools include:
soundiiz_auth_status— check whether a key is loaded and valid (calls/v1/me).soundiiz_cache_invalidatefor MCP-local cache control.
The generated catalog lives in docs/tools.md. The shorter usage guide lives in docs/tools-guide.md.
Optional Swagger UI
If you want a Swagger UI proxy for the MCP tools, use mcpo:
uvx mcpo --port 8000 --api-key "top-secret" -- node <ABS_PATH_TO_REPO>/dist/bin/cli.js
Then open http://localhost:8000/docs.
Development
Useful scripts:
npm run dev— runsrc/index.tsthroughtsx.npm run build— type-check and emit todist/.npm run start— run the built server fromdist/.npm run lint,npm run typecheck,npm test— quality gates.npm run check— lint + typecheck + test.npm run mcp:status— check whether the configured key authenticates.npm run mcp:list-tools,npm run mcp:call— local harness.npm run smoke:live— opt-in live smoke matrix against the built server.npm run sync:spec— refetch the Soundiiz OpenAPI spec fromhttps://soundiiz.com/api/doc.npm run generate:schemas— regenerate Zod schemas fromspecs/soundiiz-openapi.json.npm run generate:tools-docs— regeneratedocs/tools.md.
Project layout (planned):
src/index.ts— server bootstrap.src/config/— defaults and config loader.src/auth/— API key loading from env / file / keychain.src/core/— HTTP client, spec parser, generated tool registries.src/services/— domain services for syncs, smartlinks, user, cache.src/schemas/— shared Zod schemas for tool inputs and outputs.src/generated/— Zod schemas generated from the Soundiiz OpenAPI spec.src/tools/— MCP tool registration (curated + auto-generated + raw + auth + cache).src/infra/— logging.src/utils/— small helpers.specs/soundiiz-openapi.json— vendored copy of the Soundiiz User API spec.docs/— architecture, tool inventory, evals, design notes, launch plan.
Testing And Evals
Local checks:
npm run check
Live smoke checks are opt-in and require a Creator-plan API key:
npm run build
SOUNDIIZ_API_KEY=... npm run smoke:live
Live E2E and LLM evals use gitignored local fixture files. See docs/evals.md.
Documentation
docs/tools.md— generated tool catalog with schemas.docs/tools-guide.md— short human guide for the tool surface.docs/architecture.md— codebase overview and data flow.docs/curated-tools.md— curated tool charter and risk tiers.docs/evals.md— smoke, LLM, and manual agent eval workflow.docs/public-launch-plan.md— release awareness, registry, and launch-channel plan.docs/design-notes.md— archived design notes and future-facing ideas.
License
MIT.
Soundiiz MCP questions
How do I add Soundiiz MCP to Claude Code?
Run claude mcp add soundiiz-mcp -- npx -y soundiiz-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Soundiiz MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Soundiiz MCP provide?
It exposes 23 tools, including soundiiz_me, soundiiz_auth_status, soundiiz_syncs_list, soundiiz_sync_get, soundiiz_syncs_overview.
What kind of Soundiiz account is required?
You need a Soundiiz account on the Creator plan because the User API is currently in BETA and gated to those subscribers.
How does the server handle destructive actions like deleting syncs?
Destructive operations use a two-step confirmation flow where the first call returns a confirmId that must be used in a second call to execute the action.