Google AI Studio MCP server for AI agents

AI Studio MCP Server provides content generation capabilities using Google AI Studio/Gemini API, with support for files, conversation history, and system prompts. It follows the Model Context Protocol (MCP) to enable seamless integration with MCP clients.

Installation

Prerequisites

Node.js 20.0.0 or higher
Google AI Studio API key

Using npx (Recommended)

The simplest way to run the server is using npx:

GEMINI_API_KEY=your_api_key npx -y aistudio-mcp-server

Local Installation

Alternatively, you can install the package globally:

npm install -g aistudio-mcp-server
GEMINI_API_KEY=your_api_key aistudio-mcp-server

Configuration

API Key Setup

Set your Google AI Studio API key as an environment variable:

export GEMINI_API_KEY=your_api_key_here

Optional Configuration Parameters

Fine-tune the server's behavior with these environment variables:

GEMINI_MODEL: Gemini model to use (default: gemini-2.5-flash)
GEMINI_TIMEOUT: Request timeout in milliseconds (default: 300000 = 5 minutes)
GEMINI_MAX_OUTPUT_TOKENS: Maximum output tokens (default: 8192)
GEMINI_MAX_FILES: Maximum number of files per request (default: 10)
GEMINI_MAX_TOTAL_FILE_SIZE: Maximum total file size in MB (default: 50)
GEMINI_TEMPERATURE: Temperature for generation (0-2, default: 0.2)

Example configuration with custom parameters:

export GEMINI_API_KEY=your_api_key_here
export GEMINI_MODEL=gemini-2.5-flash
export GEMINI_TIMEOUT=600000  # 10 minutes
export GEMINI_MAX_OUTPUT_TOKENS=16384  # More output tokens
export GEMINI_MAX_FILES=5  # Limit to 5 files per request
export GEMINI_MAX_TOTAL_FILE_SIZE=100  # 100MB limit
export GEMINI_TEMPERATURE=0.7  # More creative responses

Available Tools

generate_content

This tool generates content using Gemini with comprehensive support for files, conversation history, and system prompts.

Parameters:

user_prompt (string, required): User prompt for generation
system_prompt (string, optional): System prompt to guide AI behavior
files (array, optional): Array of files to include in generation
- Each file object must have either path or content
- path (string): Path to file
- content (string): Base64 encoded file content
- type (string, optional): MIME type (auto-detected from file extension)
model (string, optional): Gemini model to use (default: gemini-2.5-flash)
temperature (number, optional): Temperature for generation (0-2, default: 0.2)

Supported file types (Gemini 2.5 models):

Images: JPG, JPEG, PNG, GIF, WebP, SVG, BMP, TIFF
Video: MP4, AVI, MOV, WEBM, FLV, MPG, WMV (up to 10 files per request)
Audio: MP3, WAV, AIFF, AAC, OGG, FLAC (up to 15MB per file)
Documents: PDF (treated as images, one page = one image)
Text: TXT, MD, JSON, XML, CSV, HTML

File limitations:

Maximum file size: 15MB per audio/video/document file
Maximum total request size: 20MB (2GB when using Cloud Storage)
Video files: Up to 10 per request
PDF files follow image pricing (one page = one image)

Usage Examples

Basic Example

{
  "user_prompt": "Analyze this image and describe what you see",
  "files": [
    {
      "path": "/path/to/image.jpg"
    }
  ]
}

PDF to Markdown Conversion

{
  "user_prompt": "Convert this PDF to well-formatted Markdown, preserving structure and formatting. Return only the Markdown content.",
  "files": [
    {
      "path": "/path/to/document.pdf"
    }
  ]
}

Using System Prompts

{
  "system_prompt": "You are a helpful document analyst specialized in technical documentation",
  "user_prompt": "Please provide a detailed explanation of the authentication methods shown in this document",
  "files": [
    {"path": "/api-docs.pdf"}
  ]
}

Working with Multiple Files

{
  "user_prompt": "Compare these documents and images",
  "files": [
    {"path": "/document.pdf"},
    {"path": "/chart.png"},
    {"content": "base64encodedcontent", "type": "image/jpeg"}
  ]
}

Common Use Cases

PDF to Markdown Conversion

{
  "user_prompt": "Convert this PDF to well-formatted Markdown, preserving structure, headings, lists, and formatting. Include table of contents if the document has sections.",
  "files": [
    {
      "path": "/path/to/document.pdf"
    }
  ]
}

Image Analysis

{
  "system_prompt": "You are an expert image analyst. Provide detailed, accurate descriptions of visual content.",
  "user_prompt": "Analyze this image and describe what you see. Include details about objects, people, text, colors, and composition.",
  "files": [
    {
      "path": "/path/to/image.jpg"
    }
  ]
}

For technical diagrams:

{
  "user_prompt": "Describe this system architecture diagram. Explain the components and their relationships.",
  "files": [
    {
      "path": "/architecture-diagram.png"
    }
  ]
}

Audio Transcription

{
  "system_prompt": "You are a professional transcription service. Provide accurate, well-formatted transcripts.",
  "user_prompt": "Please transcribe this audio file. Include speaker identification if multiple speakers are present, and format it with proper punctuation and paragraphs.",
  "files": [
    {
      "path": "/meeting-recording.mp3"
    }
  ]
}

For interviews:

{
  "user_prompt": "Transcribe this interview and provide a summary of key points discussed.",
  "files": [
    {
      "path": "/interview.wav"
    }
  ]
}

MCP Client Configuration

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "aistudio": {
      "command": "npx",
      "args": ["-y", "aistudio-mcp-server"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "GEMINI_MODEL": "gemini-2.5-flash",
        "GEMINI_TIMEOUT": "600000",
        "GEMINI_MAX_OUTPUT_TOKENS": "16384",
        "GEMINI_MAX_FILES": "10",
        "GEMINI_MAX_TOTAL_FILE_SIZE": "50",
        "GEMINI_TEMPERATURE": "0.2"
      }
    }
  }
}

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "aistudio" '{"command":"npx","args":["-y","aistudio-mcp-server"],"env":{"GEMINI_API_KEY":"your_api_key_here","GEMINI_MODEL":"gemini-2.5-flash","GEMINI_TIMEOUT":"600000","GEMINI_MAX_OUTPUT_TOKENS":"16384","GEMINI_MAX_FILES":"10","GEMINI_MAX_TOTAL_FILE_SIZE":"50","GEMINI_TEMPERATURE":"0.2"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "aistudio": {
            "command": "npx",
            "args": [
                "-y",
                "aistudio-mcp-server"
            ],
            "env": {
                "GEMINI_API_KEY": "your_api_key_here",
                "GEMINI_MODEL": "gemini-2.5-flash",
                "GEMINI_TIMEOUT": "600000",
                "GEMINI_MAX_OUTPUT_TOKENS": "16384",
                "GEMINI_MAX_FILES": "10",
                "GEMINI_MAX_TOTAL_FILE_SIZE": "50",
                "GEMINI_TEMPERATURE": "0.2"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "aistudio": {
            "command": "npx",
            "args": [
                "-y",
                "aistudio-mcp-server"
            ],
            "env": {
                "GEMINI_API_KEY": "your_api_key_here",
                "GEMINI_MODEL": "gemini-2.5-flash",
                "GEMINI_TIMEOUT": "600000",
                "GEMINI_MAX_OUTPUT_TOKENS": "16384",
                "GEMINI_MAX_FILES": "10",
                "GEMINI_MAX_TOTAL_FILE_SIZE": "50",
                "GEMINI_TEMPERATURE": "0.2"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect