OpenRouterMcp 0.0.2

🎨 dotnet-openrouter

A .NET 10 global tool and MCP server for AI-powered image and audio generation via OpenRouter

📖 Overview

dotnet-openrouter is a dual-mode .NET global tool that brings OpenRouter's media generation capabilities to your terminal and AI assistant workflow. It operates in two modes:

• CLI mode — generate images and audio directly from the command line with a simple, intuitive interface
• MCP server mode — expose generation capabilities as Model Context Protocol tools so AI assistants like Claude can call them autonomously

Both modes share the same service layer, so behaviour is identical whether you drive it from the shell or from an AI assistant.

OpenRouter provides a unified API endpoint (/api/v1/chat/completions) that routes to best-in-class models for each modality — Gemini for images, GPT-4o for audio — without requiring separate API accounts for each provider.

✨ Features

• 🖼️ Image generation — create images from text prompts with configurable aspect ratios and resolutions (up to 4K)
• 🔊 Audio generation — synthesise speech and audio from text with six voice options and multiple output formats
• 🤖 MCP server — expose all capabilities as MCP tools for seamless AI assistant integration
• 🔑 Simple authentication — store your OpenRouter API key once with a single command
• 📁 Flexible output — control output directory, filename, format, and dimensions
• 🔄 Resilient HTTP — automatic retry with exponential back-off for transient API errors
• 📦 Zero-dependency install — single dotnet tool install command, no runtime dependencies
• 🛠️ Scriptable — --robot flag outputs JSON for shell scripting and automation
• 🌐 Model-agnostic — specify any OpenRouter-compatible model by ID

⚡ Quick Start

# 1. Install the tool
dotnet tool install -g OpenRouterMcp

# 2. Save your OpenRouter API key
dotnet-openrouter auth --key sk-or-v1-...

# 3. Generate your first image
dotnet-openrouter image -d "A golden sunset over a mountain lake"

📦 Installation

Prerequisites

• .NET 10 SDK or later
• An OpenRouter account with API access

Install the Global Tool

dotnet tool install -g OpenRouterMcp

To update to the latest version:

dotnet tool update -g OpenRouterMcp

To uninstall:

dotnet tool uninstall -g OpenRouterMcp

Authenticate

Get your API key from openrouter.ai/keys, then save it:

dotnet-openrouter auth --key sk-or-v1-YOUR_API_KEY_HERE

The key is stored in ~/.openrouter-mcp/config.json with restricted file permissions (chmod 600 on Unix).

🚀 Usage

CLI Mode

Image Generation

Generate an image from a text description:

dotnet-openrouter image -d "A cat wearing a top hat, watercolour style"

All options:

dotnet-openrouter image \
  --description "A futuristic city skyline at night" \
  --model "google/gemini-2.5-flash-image-preview" \
  --aspect-ratio "16:9" \
  --size "2K" \
  --output "./images" \
  --filename "city-skyline.png"

Example output:

Image saved to ./generated-20260313-143022.png (1920x1080, 2.3 MB)

With --robot:

{
  "path": "./generated-20260313-143022.png",
  "width": 1920,
  "height": 1080,
  "bytes": 2411724
}

Audio Generation

Generate audio from a text description:

dotnet-openrouter audio -d "Welcome to our podcast. Today we explore the future of AI."

All options:

dotnet-openrouter audio \
  --description "Say hello in a warm, friendly tone" \
  --model "openai/gpt-4o-audio-preview" \
  --voice shimmer \
  --format wav \
  --output "./audio" \
  --filename "greeting.wav"

Available voices:

Example output:

Audio saved to ./generated-20260313-143055.wav (4.2s, 1.1 MB)

Authentication Management

Store your API key:

dotnet-openrouter auth --key sk-or-v1-abc123...

Output:

API key saved to ~/.openrouter-mcp/config.json

MCP Server Mode

Start the MCP server on stdio transport (used by AI assistants):

dotnet-openrouter mcp

All logging is written to stderr; stdout carries only the JSON-RPC protocol stream, so MCP hosts can safely parse it.

Claude Desktop Configuration

Add the server to your Claude Desktop configuration file.

macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "openrouter": {
      "command": "dotnet-openrouter",
      "args": ["mcp"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-YOUR_KEY_HERE"
      }
    }
  }
}

Alternatively, if you have authenticated via dotnet-openrouter auth, you can omit the env block — the tool reads the key from ~/.openrouter-mcp/config.json automatically.

VS Code / GitHub Copilot Configuration

Add to your VS Code settings.json or workspace .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "openrouter": {
        "command": "dotnet-openrouter",
        "args": ["mcp"],
        "env": {
          "OPENROUTER_API_KEY": "sk-or-v1-YOUR_KEY_HERE"
        }
      }
    }
  }
}

Once configured, ask your AI assistant to generate images or audio naturally:

"Generate a landscape image of a misty forest at dawn in a 16:9 format and save it to my Downloads folder."

"Create a short audio clip of a friendly welcome message using the shimmer voice."

See docs/MCP-CONFIGURATION.md for a complete setup guide covering all MCP clients.

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│           OpenRouter MCP Server                 │
│                                                 │
│  ┌──────────────┐         ┌─────────────────┐  │
│  │   CLI Mode   │         │   MCP Mode      │  │
│  │              │         │                 │  │
│  │  • auth      │         │  • stdio server │  │
│  │  • image     │         │  • tool calls   │  │
│  │  • audio     │         │  • JSON-RPC     │  │
│  └──────┬───────┘         └────────┬────────┘  │
│         │                          │           │
│         └──────────┬───────────────┘           │
│                    │                           │
│         ┌──────────▼──────────┐                │
│         │  Shared Services    │                │
│         │                     │                │
│         │  • ConfigService    │                │
│         │  • OpenRouterService│                │
│         └──────────┬──────────┘                │
│                    │                           │
│         ┌──────────▼──────────┐                │
│         │  OpenRouter API v1  │                │
│         │  (chat/completions) │                │
│         └─────────────────────┘                │
└─────────────────────────────────────────────────┘

The CLI commands and MCP tools are thin wrappers over a shared service layer. Both paths call identical service methods, so behaviour is consistent regardless of how the tool is invoked. The OpenRouterService handles all HTTP communication, retry logic, and response parsing; ConfigService manages API key storage and configuration.

🔐 Authentication & Security

API Key Storage

The API key is stored at ~/.openrouter-mcp/config.json:

{
  "apiKey": "sk-or-v1-..."
}

On Unix/macOS the config directory and file are created with chmod 700 and chmod 600 respectively, preventing other users from reading the key.

Environment Variable

As an alternative to file-based storage, set the OPENROUTER_API_KEY environment variable. This takes precedence over the config file, making it suitable for CI/CD pipelines:

export OPENROUTER_API_KEY=sk-or-v1-...
dotnet-openrouter image -d "A test image"

Best Practices

• Do not commit ~/.openrouter-mcp/config.json to version control
• In production or CI environments, prefer OPENROUTER_API_KEY over file storage
• Rotate your OpenRouter API key if it is ever exposed
• OpenRouter API keys are scoped per account — create a dedicated key for each tool or deployment

🎛️ Available Models

OpenRouter aggregates models from multiple providers. Browse the full catalogue at openrouter.ai/models.

Filter by modality:

• Image models — openrouter.ai/models?output_modalities=image
• Audio models — openrouter.ai/models?output_modalities=audio

Notable Image Models

Notable Audio Models

🛠️ MCP Tools Reference

These tools are exposed when running in MCP server mode (dotnet-openrouter mcp).

GenerateImage

Generate an image from a text description and save it to disk.

Example tool call (JSON-RPC):

{
  "tool": "GenerateImage",
  "arguments": {
    "description": "A serene Japanese garden in spring, cherry blossoms falling",
    "model": "google/gemini-2.5-flash-image-preview",
    "aspectRatio": "16:9",
    "imageSize": "2K",
    "outputPath": "/Users/alice/Pictures"
  }
}

GenerateAudio

Generate audio from a text description and save it to disk.

Example tool call (JSON-RPC):

{
  "tool": "GenerateAudio",
  "arguments": {
    "description": "Narrate a short introduction: Welcome to the OpenRouter podcast.",
    "model": "openai/gpt-4o-audio-preview",
    "voice": "shimmer",
    "format": "wav",
    "outputPath": "/Users/alice/Audio"
  }
}

💻 Development

Clone and Build

git clone https://github.com/brendankowitz/dotnet-openrouter.git
cd dotnet-openrouter

# Build
dotnet build

# Run tests
dotnet test

# Pack NuGet package
dotnet pack src/OpenRouterMcp/OpenRouterMcp.csproj --configuration Release --output ./packages

Install from Local Package

dotnet tool install -g OpenRouterMcp --add-source ./packages

Run Without Installing

dotnet run --project src/OpenRouterMcp -- image -d "A test image"
dotnet run --project src/OpenRouterMcp -- mcp

Project Structure

dotnet-openrouter/
├── src/
│   └── OpenRouterMcp/
│       ├── Commands/           # CLI command implementations
│       │   ├── AuthCommand.cs
│       │   ├── ImageCommand.cs
│       │   ├── AudioCommand.cs
│       │   └── McpCommand.cs
│       ├── Services/           # Business logic layer
│       │   ├── IConfigService.cs
│       │   ├── ConfigService.cs
│       │   ├── IOpenRouterService.cs
│       │   └── OpenRouterService.cs
│       ├── Models/             # Data structures
│       │   ├── OpenRouterRequest.cs
│       │   ├── OpenRouterResponse.cs
│       │   ├── ImageConfig.cs
│       │   ├── ImageResult.cs
│       │   ├── AudioConfig.cs
│       │   └── AudioResult.cs
│       ├── Mcp/                # MCP server and tools
│       │   ├── OpenRouterMcpServer.cs
│       │   └── Tools/
│       │       ├── GenerateImageTool.cs
│       │       └── GenerateAudioTool.cs
│       ├── Program.cs          # Entry point and DI setup
│       └── OpenRouterMcp.csproj
├── docs/
│   ├── MCP-CONFIGURATION.md   # MCP setup guide
│   └── features/              # Feature investigations
├── .github/
│   └── workflows/
│       ├── build.yml           # Reusable build template
│       ├── ci.yml              # CI/CD pipeline
│       └── pr.yml              # PR validation
├── .mcp/
│   └── server.json             # MCP server metadata
├── packages/                   # NuGet output (gitignored)
├── OpenRouterMcp.slnx
├── build.ps1
├── build.sh
├── GitVersion.yml
├── LICENSE
└── README.md

Key Dependencies

🤝 Contributing

Contributions are welcome. Please follow these steps:

1. Fork the repository at github.com/brendankowitz/dotnet-openrouter
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes, ensuring all existing tests pass
4. Add tests for new functionality
5. Submit a pull request with a clear description of the change

For significant changes, please open an issue first to discuss the approach.

📄 License

This project is licensed under the MIT License. See LICENSE for details.

🔗 Related Projects

• dotnet-gmail-mcp — the sibling project that inspired this architecture; provides Gmail integration as a .NET global tool and MCP server
• OpenRouter — the unified API gateway this tool connects to
• Model Context Protocol — the open standard for AI assistant tool integration
• ModelContextProtocol .NET SDK — the SDK used to implement the MCP server

<p align="center"> Built with .NET 10 · Powered by <a href="https://openrouter.ai">OpenRouter</a> · MCP Enabled </p>