Gaia MCP Server

⚠️ DEPRECATED

This repository is deprecated and is no longer actively maintained. Please use the new Go implementation instead:

👉 github.com/SipherAGI/gaia-mcp-go

The Go implementation provides better performance, easier installation, and active maintenance.

An MCP (Model Context Protocol) server implementation for ProtoGaia, supporting both stdio and SSE (Server-Sent Events) communication methods.

Table of Contents

• Introduction
• Installation
• Usage
  • Integrate with Claude Desktop
  • Using Stdio Method
  • Using SSE Method
• Understanding MCP
• API Endpoints
• Supported Tools
• Notice

Introduction

This package contains a TypeScript implementation of an MCP server for ProtoGaia. It provides a standardized way for LLMs (Large Language Models) to communicate with external tools and services using the Model Context Protocol.

Installation

You can use Gaia MCP Server in multiple ways:

Using with npx (No Installation)

Run the server directly using npx without installing:

# Run in SSE mode
npx @ather-mcp/gaia-mcp-server sse

# Run in stdio mode
npx @ather-mcp/gaia-mcp-server stdio --api-key=your-api-key

Global Installation

Install the package globally to run from anywhere:

npm install -g @ather-mcp/gaia-mcp-server

Then run it from any terminal:

# Run in SSE mode
gaia-mcp-server sse

# Run in stdio mode
gaia-mcp-server stdio --api-key=your-api-key

Usage

The server can be run in two modes: stdio or SSE. You can choose which mode to run using the command-line interface.

Integrate with Claude Desktop

You can integrate Gaia MCP Server with Claude Desktop to generate images directly in your conversations:

1. Get Your Gaia API Key:

   • Log in to Gaia's website
   • Go to your account settings via your profile picture
   • Navigate to the "Security" section
   • Create a new API key and copy it

2. Configure Claude Desktop:

   • Open Claude Desktop
   • Go to Settings (File > Settings on Windows, Claude > Settings on Mac)
   • Click the "Developer" tab
   • Click the "Edit config" button
   • Replace the content with one of these configurations:

   If you've installed the package globally:

   {
     "mcpServers": {
       "gaia-mcp-server": {
         "command": "gaia-mcp-server",
         "args": ["stdio", "--api-key=YOUR_GAIA_API_KEY"]
       }
     }
   }

   If you prefer to use npx (no installation):

   {
     "mcpServers": {
       "gaia-mcp-server": {
         "command": "npx",
         "args": ["gaia-mcp-server", "stdio", "--api-key=YOUR_GAIA_API_KEY"]
       }
     }
   }

   Replace YOUR_GAIA_API_KEY with your actual Gaia API key.

3. Restart Claude Desktop

4. Test the Integration:

   • Start a new conversation
   • Ask Claude to generate an image (e.g., "Generate an image of a sunset over mountains")
   • You should see the image appear in your conversation

For more detailed instructions and troubleshooting, see our Claude Desktop Integration Guide.

Using Stdio Method

The stdio method is useful for direct communication with the server via standard input/output streams, typically used when integrating with CLI tools or developing locally.

To start the server in stdio mode:

# Using npx
npx @ather-mcp/gaia-mcp-server stdio --api-key=your-api-key

# Using globally installed package
gaia-mcp-server stdio --api-key=your-api-key

You can also specify a custom API URL:

npx @ather-mcp/gaia-mcp-server stdio --api-key=your-api-key --api-url=https://your-custom-api-url

With the stdio method, communication with the server happens through stdin/stdout, following the MCP protocol format.

Example of sending a message through stdio:

{ "type": "message", "data": { "content": "Your message content here" } }

Using SSE Method

The SSE method allows for server-sent events communication over HTTP, making it suitable for web applications.

To start the server in SSE mode:

# Using npx
npx @ather-mcp/gaia-mcp-server sse

# Using globally installed package
gaia-mcp-server sse

The server will start on the port specified in your .env file (default: 3000).

Connecting to the SSE Server

To establish an SSE connection:

1. Create an EventSource connection to /sse endpoint with your Gaia's account API Key. More information about creating your API key can be found at here.
2. Send messages via POST requests to /messages endpoint

Client-side JavaScript example:

// Establish SSE connection
const eventSource = new EventSource('http://localhost:3000/sse?apiKey=your-gaia-account-api-key');
const sessionId = ''; // Will be populated from the first message

// Listen for messages
eventSource.onmessage = event => {
  const data = JSON.parse(event.data);

  // Store session ID from first message
  if (data.sessionId && !sessionId) {
    sessionId = data.sessionId;
  }

  console.log('Received:', data);
};

// Send a message
async function sendMessage(content) {
  await fetch('http://localhost:3000/messages', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sessionId,
      message: {
        type: 'message',
        data: { content },
      },
    }),
  });
}

Understanding MCP

The Model Context Protocol (MCP) is a standardized communication protocol that enables LLMs to interact with external tools and services. More information can be found at modelcontextprotocol.io.

Key MCP concepts:

• Messages: The basic unit of communication in the protocol
• Tools: Functions that can be called by the model
• Transport Layers: Methods of communication (stdio, SSE, etc.)
• Sessions: Stateful interactions between the model and server

This server implementation uses the @modelcontextprotocol/sdk package to handle the protocol details.

API Endpoints

When running in SSE mode, the following endpoints are available:

• GET /sse: Establishes an SSE connection
• POST /messages: Sends messages to the server
• GET /health: Health check endpoint
• GET /: Basic information about the server

Supported Tools

The Gaia MCP Server provides several AI image generation and manipulation tools that can be called by LLMs:

• upload-image: Upload images to the Gaia platform from URLs
• create-style: Create a new style in the Gaia platform using provided images
• generate-image: Generate images with Protogaia based on text prompts
• remix: Create new variations of an existing image
• face-enhancer: Enhance face details in an existing image
• upscaler: Enhance the resolution quality of image

Each tool is registered with the MCP server and can be invoked according to the Model Context Protocol standard.

License

Apache License 2.0

Notice

• To utilize the generative image functionality, the user must possess GAIA credits. You can check your remaining credits and purchase more here.