@mindstone/mcp-server-elevenlabs 0.2.2

package/LICENSE

@@ -0,0 +1,97 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Mindstone Learning Limited
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+**Licensor**: Mindstone Learning Limited
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+**Software**: ElevenLabs MCP Server
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A "Competing
+Use" means making the Software available to third parties as a commercial
+hosted service that directly competes with any product or service provided by
+the Licensor.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, OF
+ANY CHARACTER INCLUDING DAMAGES FOR LOSS OF GOODWILL, LOST PROFITS, LOST SALES
+OR BUSINESS, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, LOST CONTENT,
+DATA OR DATA USE, BREACH OF DUTY OF GOOD FAITH, OR ANY AND ALL OTHER DAMAGES
+OR LOSSES OF ANY KIND OR NATURE WHATSOEVER (WHETHER DIRECT, INDIRECT, SPECIAL,
+COLLATERAL, INCIDENTAL, CONSEQUENTIAL OR OTHERWISE) ARISING OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THIS LICENSE, EVEN IF SUCH PARTY SHALL HAVE
+BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+### Trademark
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Change Date
+
+Four years from the date the Software is made available under these Terms and
+Conditions: **2030-04-08**
+
+## Change License
+
+MIT License
+
+## License Details
+
+| Parameter | Value |
+|---|---|
+| Licensor | Mindstone Learning Limited |
+| Software | ElevenLabs MCP Server |
+| Use Limitation | Competing Use |
+| Change Date | 2030-04-08 |
+| Change License | MIT |

package/README.md

@@ -0,0 +1,99 @@
+# @mindstone/mcp-server-elevenlabs
+
+[![npm version](https://img.shields.io/npm/v/@mindstone/mcp-server-elevenlabs.svg)](https://www.npmjs.com/package/@mindstone/mcp-server-elevenlabs)
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](./LICENSE)
+
+ElevenLabs MCP server for Model Context Protocol hosts. Generate speech, music, and sound effects, browse voices, and transcribe audio using the ElevenLabs API through a standardised MCP interface.
+
+## Requirements
+
+- Node.js 20+
+- npm
+
+## Quick Start
+
+### Install & build
+
+```bash
+cd <path-to-repo>/connectors/elevenlabs
+npm install
+npm run build
+```
+
+### npx (once published)
+
+```bash
+npx -y @mindstone/mcp-server-elevenlabs
+```
+
+### Local
+
+```bash
+node dist/index.js
+```
+
+## Configuration
+
+### Environment variables
+
+- `ELEVENLABS_API_KEY` — ElevenLabs API key (starts with `sk_`)
+- `MCP_HOST_BRIDGE_STATE` — optional path to a host bridge state file used for credential management
+- `MINDSTONE_REBEL_BRIDGE_STATE` — backwards-compatible alias for `MCP_HOST_BRIDGE_STATE`
+
+## Host configuration examples
+
+### Claude Desktop / Cursor
+
+```json
+{
+  "mcpServers": {
+    "ElevenLabs": {
+      "command": "npx",
+      "args": ["-y", "@mindstone/mcp-server-elevenlabs"],
+      "env": {
+        "ELEVENLABS_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Local development (no npm publish needed)
+
+```json
+{
+  "mcpServers": {
+    "ElevenLabs": {
+      "command": "node",
+      "args": ["<path-to-repo>/connectors/elevenlabs/dist/index.js"],
+      "env": {
+        "ELEVENLABS_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Tools (8)
+
+### Configuration
+- `configure_elevenlabs_api_key` — Save your ElevenLabs API key
+
+### Voices
+- `list_voices` — Search and browse available ElevenLabs voices
+
+### Speech
+- `generate_speech` — Generate spoken audio from text using text-to-speech
+- `generate_sound_effect` — Generate sound effects from a text description
+
+### Music
+- `generate_music` — Generate music from a text prompt
+- `create_music_plan` — Create a composition plan for music generation (free)
+- `generate_music_from_plan` — Generate music from a composition plan
+
+### Transcription
+- `transcribe_audio` — Transcribe speech from an audio file to text
+
+## Licence
+
+[FSL-1.1-MIT](./LICENSE) — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.

package/dist/auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ElevenLabs authentication module.
+ *
+ * Simple API key management — stored via env var (ELEVENLABS_API_KEY)
+ * or configured at runtime via the configure_elevenlabs_api_key tool.
+ *
+ * Auth: xi-api-key header on all API requests (NOT Bearer).
+ */
+/**
+ * Get the current API key.
+ */
+export declare function getApiKey(): string;
+/**
+ * Set the API key at runtime (from configure tool).
+ */
+export declare function setApiKey(key: string): void;
+/**
+ * Check if an API key is configured.
+ */
+export declare function hasApiKey(): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,29 @@
+/**
+ * ElevenLabs authentication module.
+ *
+ * Simple API key management — stored via env var (ELEVENLABS_API_KEY)
+ * or configured at runtime via the configure_elevenlabs_api_key tool.
+ *
+ * Auth: xi-api-key header on all API requests (NOT Bearer).
+ */
+/** Runtime API key — starts from env, can be updated via configure tool. */
+let apiKey = process.env.ELEVENLABS_API_KEY ?? '';
+/**
+ * Get the current API key.
+ */
+export function getApiKey() {
+    return apiKey;
+}
+/**
+ * Set the API key at runtime (from configure tool).
+ */
+export function setApiKey(key) {
+    apiKey = key;
+}
+/**
+ * Check if an API key is configured.
+ */
+export function hasApiKey() {
+    return apiKey.trim().length > 0;
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. the host application)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. the host application)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return { success: false, error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.` };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ElevenLabs API HTTP client.
+ *
+ * Centralises xi-api-key header injection, error handling, rate-limit
+ * messaging, and timeout handling for all ElevenLabs API calls.
+ *
+ * Auth: xi-api-key: {key} (NOT Bearer, NOT Basic)
+ * Base URL: https://api.elevenlabs.io/v1
+ * Voices URL: https://api.elevenlabs.io/v2/voices
+ */
+import { type AudioResult } from './types.js';
+/**
+ * Make an authenticated request to the ElevenLabs API.
+ * Returns a raw Response object.
+ */
+export declare function elevenLabsFetch(apiKey: string, urlPath: string, options?: RequestInit): Promise<Response>;
+/**
+ * Make a JSON API call and parse the response.
+ */
+export declare function elevenLabsJson<T>(apiKey: string, urlPath: string, options?: RequestInit): Promise<T>;
+/**
+ * Make an API call that returns raw audio binary. Save to file and return path.
+ */
+export declare function elevenLabsAudio(apiKey: string, urlPath: string, options?: RequestInit, fileExtension?: string): Promise<AudioResult>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,108 @@
+/**
+ * ElevenLabs API HTTP client.
+ *
+ * Centralises xi-api-key header injection, error handling, rate-limit
+ * messaging, and timeout handling for all ElevenLabs API calls.
+ *
+ * Auth: xi-api-key: {key} (NOT Bearer, NOT Basic)
+ * Base URL: https://api.elevenlabs.io/v1
+ * Voices URL: https://api.elevenlabs.io/v2/voices
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as crypto from 'crypto';
+import { ElevenLabsError, REQUEST_TIMEOUT_MS, getErrorResolution, } from './types.js';
+const ELEVENLABS_API_BASE = 'https://api.elevenlabs.io/v1';
+/**
+ * Make an authenticated request to the ElevenLabs API.
+ * Returns a raw Response object.
+ */
+export async function elevenLabsFetch(apiKey, urlPath, options = {}) {
+    if (!apiKey || apiKey.trim().length === 0) {
+        throw new ElevenLabsError('ElevenLabs API key not configured', 'AUTH_REQUIRED', 'Configure your ElevenLabs API key in Settings. Get one at https://elevenlabs.io/app/settings/api-keys');
+    }
+    const url = urlPath.startsWith('https://')
+        ? urlPath
+        : `${ELEVENLABS_API_BASE}${urlPath}`;
+    const headers = {
+        'xi-api-key': apiKey,
+        ...(options.headers || {}),
+    };
+    // Only set Content-Type for JSON bodies (not FormData)
+    if (!(options.body instanceof FormData) && !headers['Content-Type']) {
+        headers['Content-Type'] = 'application/json';
+    }
+    console.error(`[ElevenLabs API] ${options.method || 'GET'} ${url}`);
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new ElevenLabsError('Request to ElevenLabs API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the ElevenLabs API is available.');
+        }
+        throw error;
+    }
+    // Handle rate limiting
+    if (response.status === 429) {
+        throw new ElevenLabsError('Rate limited. Please wait a moment before retrying.', 'RATE_LIMITED', getErrorResolution(429));
+    }
+    // Handle auth errors
+    if (response.status === 401) {
+        throw new ElevenLabsError('Authentication failed', 'AUTH_FAILED', getErrorResolution(401));
+    }
+    if (response.status === 403) {
+        let detail = '';
+        try {
+            const errBody = await response.clone().json();
+            if (typeof errBody.detail === 'string') {
+                detail = errBody.detail;
+            }
+            else if (errBody.detail?.message) {
+                detail = errBody.detail.message;
+            }
+        }
+        catch { /* not JSON */ }
+        throw new ElevenLabsError(`Access forbidden: ${detail || 'insufficient permissions or quota'}`, 'AUTH_FAILED', getErrorResolution(403, detail));
+    }
+    // Handle other errors
+    if (!response.ok) {
+        let detail = '';
+        try {
+            const errBody = await response.clone().json();
+            if (typeof errBody.detail === 'string') {
+                detail = errBody.detail;
+            }
+            else if (errBody.detail?.message) {
+                detail = errBody.detail.message;
+            }
+        }
+        catch { /* not JSON */ }
+        throw new ElevenLabsError(`ElevenLabs API error (HTTP ${response.status}): ${detail || response.statusText}`, `HTTP_${response.status}`, getErrorResolution(response.status, detail));
+    }
+    return response;
+}
+/**
+ * Make a JSON API call and parse the response.
+ */
+export async function elevenLabsJson(apiKey, urlPath, options = {}) {
+    const response = await elevenLabsFetch(apiKey, urlPath, options);
+    return (await response.json());
+}
+/**
+ * Make an API call that returns raw audio binary. Save to file and return path.
+ */
+export async function elevenLabsAudio(apiKey, urlPath, options = {}, fileExtension = 'mp3') {
+    const response = await elevenLabsFetch(apiKey, urlPath, options);
+    const buffer = Buffer.from(await response.arrayBuffer());
+    const fileName = `elevenlabs_${crypto.randomUUID()}.${fileExtension}`;
+    const filePath = path.join(os.tmpdir(), fileName);
+    fs.writeFileSync(filePath, buffer);
+    return { filePath, sizeBytes: buffer.length };
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * ElevenLabs MCP Server
+ *
+ * Provides ElevenLabs audio integration via Model Context Protocol.
+ * Music generation, text-to-speech, sound effects, voice browsing, transcription.
+ *
+ * Environment variables:
+ * - ELEVENLABS_API_KEY: ElevenLabs API key (required, starts with sk_)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (primary, optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy/deprecated bridge state path (optional)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * ElevenLabs MCP Server
+ *
+ * Provides ElevenLabs audio integration via Model Context Protocol.
+ * Music generation, text-to-speech, sound effects, voice browsing, transcription.
+ *
+ * Environment variables:
+ * - ELEVENLABS_API_KEY: ElevenLabs API key (required, starts with sk_)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (primary, optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy/deprecated bridge state path (optional)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('ElevenLabs MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,18 @@
+import { createRequire } from 'node:module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerMusicTools, registerSpeechTools, registerVoiceTools, registerTranscriptionTools, } from './tools/index.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export function createServer() {
+    const server = new McpServer({
+        name: 'elevenlabs-mcp-server',
+        version: pkg.version,
+    });
+    registerConfigureTools(server);
+    registerMusicTools(server);
+    registerSpeechTools(server);
+    registerVoiceTools(server);
+    registerTranscriptionTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/configure.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerConfigureTools(server: McpServer): void;
+//# sourceMappingURL=configure.d.ts.map

package/dist/tools/configure.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { setApiKey } from '../auth.js';
+import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
+import { ElevenLabsError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerConfigureTools(server) {
+    server.registerTool('configure_elevenlabs_api_key', {
+        description: 'Save your ElevenLabs API key. Call this when the user provides their key. ' +
+            'WHERE TO GET A KEY: Go to https://elevenlabs.io/app/settings/api-keys → Create new API key → Copy the key (starts with "sk_"). ' +
+            'FREE TIER: 10,000 characters/month for TTS. Music generation requires a paid plan.',
+        inputSchema: z.object({
+            api_key: z.string().min(1).describe('ElevenLabs API key (starts with "sk_").'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    }, withErrorHandling(async (args) => {
+        const key = args.api_key.trim();
+        // If bridge is available, persist via bridge
+        if (BRIDGE_STATE_PATH) {
+            try {
+                const result = await bridgeRequest('/bundled/elevenlabs/configure', { apiKey: key });
+                if (result.success) {
+                    setApiKey(key);
+                    const message = result.warning
+                        ? `ElevenLabs API key configured successfully. Note: ${result.warning}`
+                        : 'ElevenLabs API key configured successfully! You can now generate music, speech, sound effects, and more.';
+                    return JSON.stringify({ ok: true, message });
+                }
+                // Bridge returned failure — surface as error, do NOT fall through
+                throw new ElevenLabsError(result.error || 'Bridge configuration failed', 'BRIDGE_ERROR', 'The host app bridge rejected the configuration request. Check the host app logs.');
+            }
+            catch (error) {
+                if (error instanceof ElevenLabsError)
+                    throw error;
+                // Bridge request failed (network, timeout, etc.) — surface as error
+                throw new ElevenLabsError(`Bridge request failed: ${error instanceof Error ? error.message : String(error)}`, 'BRIDGE_ERROR', 'Could not reach the host app bridge. Ensure the host app is running.');
+            }
+        }
+        // No bridge — store in-memory
+        setApiKey(key);
+        return JSON.stringify({
+            ok: true,
+            message: 'ElevenLabs API key configured successfully! You can now generate music, speech, sound effects, and more.',
+        });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,6 @@
+export { registerConfigureTools } from './configure.js';
+export { registerMusicTools } from './music.js';
+export { registerSpeechTools } from './speech.js';
+export { registerVoiceTools } from './voices.js';
+export { registerTranscriptionTools } from './transcription.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,6 @@
+export { registerConfigureTools } from './configure.js';
+export { registerMusicTools } from './music.js';
+export { registerSpeechTools } from './speech.js';
+export { registerVoiceTools } from './voices.js';
+export { registerTranscriptionTools } from './transcription.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/music.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerMusicTools(server: McpServer): void;
+//# sourceMappingURL=music.d.ts.map