# Soundiiz Mcp

> Local-first MCP server for safe AI access to Soundiiz syncs and SmartLinks. Read-only by default with confirmation-gated writes.

- **Type:** MCP server
- **Install:** `agentstack add mcp-basic-bit-soundiiz-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BASIC-BIT](https://agentstack.voostack.com/s/basic-bit)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [BASIC-BIT](https://github.com/BASIC-BIT)
- **Source:** https://github.com/BASIC-BIT/soundiiz-mcp
- **Website:** https://github.com/BASIC-BIT/soundiiz-mcp

## Install

```sh
agentstack add mcp-basic-bit-soundiiz-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Soundiiz MCP

An MCP server for [Soundiiz](https://soundiiz.com). Lets your AI assistant inspect your sync jobs and SmartLinks across streaming services, trigger syncs, and clean up stale links.

Built for [Claude Desktop](https://claude.ai/download), [OpenCode](https://opencode.ai/), and any other [Model Context Protocol](https://modelcontextprotocol.io/) 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:
  1. The first call returns a `confirmId` and a recap of what would happen.
  2. Re-call the same tool with the same args plus that `confirmId` to execute. The token is single-use and bound to the tool name + arg hash.

Knobs:

- `writes.confirmDestructive = false` — skip the confirm step on deletes (one-call writes).
- `writes.allow = false` (or `SOUNDIIZ_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](https://soundiiz.com/webapp/settings/api).

Install from source:

```bash
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.

```json
{
  "mcpServers": {
    "soundiiz": {
      "command": "node",
      "args": ["/dist/bin/cli.js"],
      "env": {
        "SOUNDIIZ_API_KEY": "",
        "SOUNDIIZ_MCP_USER_AGENT": "your-name (email@example.com)"
      }
    }
  }
}
```

For active development, point at the TypeScript entrypoint instead:

```json
{
  "mcpServers": {
    "soundiiz-dev": {
      "command": "npx",
      "args": ["tsx", "/src/index.ts"],
      "env": {
        "SOUNDIIZ_API_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`:

```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 to `https://api.soundiiz.com`.
- `SOUNDIIZ_MCP_LOG_LEVEL`: `debug`, `info`, `warn`, or `error`.
- `SOUNDIIZ_MCP_KEY_STORE`: `env`, `file`, or `keychain`.
- `SOUNDIIZ_MCP_KEY_FILE`: file path when `SOUNDIIZ_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 raw `soundiiz_call` tool. 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_` for GET operations from the Soundiiz OpenAPI spec.
- **Auto-generated write tools** named `soundiiz_write_` for non-GET operations.

Local-only tools include:

- `soundiiz_auth_status` — check whether a key is loaded and valid (calls `/v1/me`).
- `soundiiz_cache_invalidate` for 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`:

```bash
uvx mcpo --port 8000 --api-key "top-secret" -- node /dist/bin/cli.js
```

Then open `http://localhost:8000/docs`.

## Development

Useful scripts:

- `npm run dev` — run `src/index.ts` through `tsx`.
- `npm run build` — type-check and emit to `dist/`.
- `npm run start` — run the built server from `dist/`.
- `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 from `https://soundiiz.com/api/doc`.
- `npm run generate:schemas` — regenerate Zod schemas from `specs/soundiiz-openapi.json`.
- `npm run generate:tools-docs` — regenerate `docs/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:

```bash
npm run check
```

Live smoke checks are opt-in and require a Creator-plan API key:

```bash
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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BASIC-BIT](https://github.com/BASIC-BIT)
- **Source:** [BASIC-BIT/soundiiz-mcp](https://github.com/BASIC-BIT/soundiiz-mcp)
- **License:** MIT
- **Homepage:** https://github.com/BASIC-BIT/soundiiz-mcp

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-basic-bit-soundiiz-mcp
- Seller: https://agentstack.voostack.com/s/basic-bit
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.