Audius MCP Server (Code Mode)

A Code Mode MCP server that gives LLMs full access to the Audius music platform and Open Audio Protocol. Instead of 100+ individual tools, it uses two meta-tools — search and execute — to compress the entire Audius API into ~1,000 tokens of context.

Built with Effect-TS. Runs a QuickJS WASM sandbox for secure code execution.

How It Works

LLM ──► search("trending tracks")     → discovers GET /tracks/trending
    ──► execute("audius.request(...)") → runs code in sandbox, returns results

The LLM writes JavaScript that runs in an isolated sandbox with an authenticated audius.request() client. No API keys in the prompt, no tool explosion, no round-trip overhead.

Tools

Tool	What it does
search	Discover API endpoints by tag, path, method, or keyword
execute	Run JavaScript against the Audius API in a QuickJS sandbox
play	Open a track in the Audius desktop app or browser
subgraph	Query on-chain protocol data (staking, governance, nodes) via The Graph

Quick Start

# Install
git clone https://github.com/glassBead-tc/audius-mcp-atris.git
cd audius-mcp-atris
pnpm install

# Configure
echo 'AUDIUS_API_KEY=your_key_here' > .env

# Build & run
pnpm dev

Getting API Keys

Audius API Key (required)

1. Go to audius.co/settings and sign in (or create an account)
2. Scroll to Developer Apps and create a new app
3. Copy the API Key — this goes in your .env as AUDIUS_API_KEY
4. Optionally copy the API Secret if you plan to do write operations (uploads, favorites)

Alternatively, get credentials at api.audius.co/plans.

The Graph API Key (optional, for subgraph tool)

The subgraph tool queries on-chain protocol data (staking, governance, nodes). It requires a Graph API key:

1. Go to thegraph.com/studio and sign in
2. Create an API key (video tutorial)
3. Add it to your .env as GRAPH_API_KEY

Without this key, the subgraph tool will return an auth error. All other tools work fine without it.

Connect to Claude

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "audius-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Claude Desktop

Add to claude_mcp_config.json:

{
  "mcpServers": {
    "audius": {
      "command": "node",
      "args": ["/path/to/audius-mcp-atris/dist/index.js"],
      "env": {
        "AUDIUS_API_KEY": "your_key_here"
      }
    }
  }
}

Example Conversations

"What's trending on Audius right now?"

// LLM calls search({ tag: "tracks" }), then:
return await audius.request('GET', '/tracks/trending', { query: { limit: 5 } })

"Find deadmau5 and show me his top tracks"

const users = await audius.request('GET', '/users/search', { query: { query: 'deadmau5' } })
const userId = users.data[0].id
const tracks = await audius.request('GET', '/users/' + userId + '/tracks', { query: { sort: 'plays' } })
return tracks.data.map(t => ({ title: t.title, plays: t.play_count }))

"How much $AUDIO is staked in the protocol?"

{ audiusNetworks(first: 1) { totalTokensStaked totalTokensDelegated totalSupply } }

Architecture

src/
├── index.ts                    # Entry point — Effect layers, HTTP server
├── AppConfig.ts                # Env var config (AUDIUS_API_KEY, PORT)
├── mcp/
│   ├── McpSchema.ts            # MCP 2025-11-25 protocol (Effect Schema)
│   ├── McpSerialization.ts     # JSON-RPC ↔ Effect RPC bridge
│   ├── McpServer.ts            # Request dispatch (initialize, tools/*)
│   └── McpServerTransport.ts   # Streamable HTTP on /mcp
├── api/
│   ├── SpecLoader.ts           # Fetch + resolve Audius swagger.yaml
│   ├── SpecIndex.ts            # Searchable index over parsed spec
│   └── AudiusClient.ts         # Authenticated HTTP client
├── tools/
│   ├── SearchTool.ts           # search tool
│   ├── ExecuteTool.ts          # execute tool
│   ├── PlayTool.ts             # play tool
│   └── SubgraphTool.ts         # subgraph tool
└── sandbox/
    ├── Sandbox.ts              # QuickJS WASM sandbox
    └── TypeGenerator.ts        # TS declarations from spec

Every component is an Effect service (Context.Tag) composed via Layer. The sandbox uses QuickJSDeferredPromise to support unlimited chained await calls.

Environment Variables

Variable	Required	Description
AUDIUS_API_KEY	Yes	API key from audius.co/settings
PORT	No	HTTP server port (default: 3000)
GRAPH_API_KEY	No	The Graph API key for subgraph queries

Development

pnpm build    # Compile TypeScript
pnpm start    # Run compiled server
pnpm dev      # Build + run
pnpm test     # Run tests

Security

• Sandbox isolation: LLM-generated code runs in QuickJS WASM — no filesystem, no network, no env vars
• No raw fetch: Only audius.request() is available, hardcoded to api.audius.co
• SSRF protection: API paths must start with / and cannot contain @
• Memory cap: 64MB per execution
• Timeout: 30s default, configurable per call
• Fresh context: No state leaks between executions

Protocol

• MCP version: 2025-11-25
• Transport: Streamable HTTP at POST /mcp
• Sessions: MCP-Session-Id header, in-memory (stateless-ready)

Open Audio Protocol

This server is built on the Open Audio Protocol — the decentralized global music database. Audius is one application layer on top of OAP. The subgraph tool provides direct access to on-chain protocol data.

License

MIT