MCPollinations Multimodal MCP Server

Instructions

Implementation Reference

• src/services/audioService.js:20-91 (handler)

  Core respondAudio function: fetches audio from Pollinations API using text-to-speech endpoint, converts to base64, returns data and metadata.

  export async function respondAudio(prompt, voice = "alloy", seed, voiceInstructions, authConfig = null) {
    if (!prompt || typeof prompt !== 'string') {
      throw new Error('Prompt is required and must be a string');
    }
  
    // Build the query parameters
    const queryParams = new URLSearchParams();
    queryParams.append('model', 'openai-audio'); // Required for audio generation
    queryParams.append('voice', voice);
    if (seed !== undefined) queryParams.append('seed', seed);
  
    // Construct the URL
    let finalPrompt = prompt;
  
    // Add voice instructions if provided
    if (voiceInstructions) {
      finalPrompt = `${voiceInstructions}\n\n${prompt}`;
    }
  
    const encodedPrompt = encodeURIComponent(finalPrompt);
    const baseUrl = 'https://text.pollinations.ai';
    let url = `${baseUrl}/${encodedPrompt}`;
  
    // Add query parameters
    const queryString = queryParams.toString();
    url += `?${queryString}`;
  
    try {
      // Prepare fetch options with optional auth headers
      const fetchOptions = {};
      if (authConfig) {
        fetchOptions.headers = {};
        if (authConfig.token) {
          fetchOptions.headers['Authorization'] = `Bearer ${authConfig.token}`;
        }
        if (authConfig.referrer) {
          fetchOptions.headers['Referer'] = authConfig.referrer;
        }
      }
  
      // Fetch the audio from the URL
      const response = await fetch(url, fetchOptions);
  
      if (!response.ok) {
        throw new Error(`Failed to generate audio: ${response.statusText}`);
      }
  
      // Get the audio data as an ArrayBuffer
      const audioBuffer = await response.arrayBuffer();
  
      // Convert the ArrayBuffer to a base64 string
      const base64Data = Buffer.from(audioBuffer).toString('base64');
  
      // Determine the mime type from the response headers or default to audio/mpeg
      const contentType = response.headers.get('content-type') || 'audio/mpeg';
  
      return {
        data: base64Data,
        mimeType: contentType,
        metadata: {
          prompt,
          voice,
          model: 'openai-audio',
          seed,
          voiceInstructions
        }
      };
    } catch (error) {
      log('Error generating audio:', error);
      throw error;
    }
  }

• pollinations-mcp-server.js:257-297 (handler)

  MCP server CallToolRequest handler for respondAudio: calls core function, saves/plays audio file, returns metadata response.

  } else if (name === 'respondAudio') {
    try {
      const { prompt, voice = defaultConfig.audio.voice, seed, voiceInstructions } = args;
      const result = await respondAudio(prompt, voice, seed, voiceInstructions, finalAuthConfig);
  
      // Save audio to a temporary file
      const tempDir = os.tmpdir();
      const tempFilePath = path.join(tempDir, `pollinations-audio-${Date.now()}.mp3`);
  
      // Decode base64 and write to file
      fs.writeFileSync(tempFilePath, Buffer.from(result.data, 'base64'));
  
      // Play the audio file
      audioPlayer.play(tempFilePath, (err) => {
        if (err) log('Error playing audio:', err);
  
        // Clean up the temporary file after playing
        try {
          fs.unlinkSync(tempFilePath);
        } catch (cleanupErr) {
          log('Error cleaning up temp file:', cleanupErr);
        }
      });
  
      return {
        content: [
          {
            type: 'text',
            text: `Audio has been played.\n\nAudio metadata: ${JSON.stringify(result.metadata, null, 2)}`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          { type: 'text', text: `Error generating audio: ${error.message}` }
        ],
        isError: true
      };
    }
  } else if (name === 'listImageModels') {

• src/services/audioSchema.js:8-29 (schema)

  Input schema for respondAudio tool defining parameters: prompt (required), voice, seed.

  export const respondAudioSchema = {
    name: 'respondAudio',
    description: 'Generate an audio response to a text prompt and play it through the system',
    inputSchema: {
      type: 'object',
      properties: {
        prompt: {
          type: 'string',
          description: 'The text prompt to respond to with audio'
        },
        voice: {
          type: 'string',
          description: 'Voice to use for audio generation (default: "alloy"). Available options: "alloy", "echo", "fable", "onyx", "nova", "shimmer", "coral", "verse", "ballad", "ash", "sage", "amuch", "dan"'
        },
        seed: {
          type: 'number',
          description: 'Seed for reproducible results (default: random)'
        }
      },
      required: ['prompt']
    }
  };

• pollinations-mcp-server.js:198-200 (registration)

  MCP server registration of all tools including respondAudio via getAllToolSchemas() in ListToolsRequestHandler.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: getAllToolSchemas()
  }));

• src/index.js:9-23 (registration)

  Import and re-export of respondAudio function for use across the codebase.

  import { respondAudio, listAudioVoices } from './services/audioService.js';
  import { respondText, listTextModels } from './services/textService.js';
  
  
  // Export all service functions
  export {
    // Image services
    generateImageUrl,
    generateImage,
    editImage,
    generateImageFromReference,
    listImageModels,
  
    // Audio services
    respondAudio,