# Elgato MCP Server

[![npm version](https://img.shields.io/npm/v/@elgato/mcp-server.svg)](https://www.npmjs.com/package/@elgato/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server that bridges AI assistants (like Claude Desktop) with Elgato apps.

## Overview

The Elgato MCP Server acts as a protocol bridge between MCP clients and Elgato apps via IPC:

```
MCP Client <--MCP Transport--> Bridge <--Unix Socket/Named Pipe--> Elgato App
```

**Key Features:**

- 🔌 **Dynamic Tool Discovery** — Automatically discovers and exposes tools from connected Elgato apps via MCP
- 🚀 **Dual Transport Support** — stdio (for Claude Desktop) and HTTP (for web clients)
- 🌐 **ngrok Integration** — Optional public tunnel for remote access
- 🔄 **Hot Reconnection** — Automatically reconnects when apps become available
- 💻 **Cross-Platform** — Supports Windows and macOS
- 📢 **Notification Forwarding** — Forwards app notifications to connected MCP clients

## Installation

```bash
# Global installation (recommended)
npm install -g @elgato/mcp-server

# Or with pnpm
pnpm add -g @elgato/mcp-server
```

## Running without Installation

You can run the Elgato MCP Server directly without installing it globally using `npx`:

```bash
# Run with stdio transport (default)
npx -y @elgato/mcp-server@latest

# Run with HTTP transport
npx -y @elgato/mcp-server@latest --http

# Run with HTTP transport on a custom port
npx -y @elgato/mcp-server@latest --http --port 3000

# Run with ngrok tunnel
NGROK_AUTHTOKEN=your_token npx -y @elgato/mcp-server@latest --http --ngrok

# Run with verbose logging
npx -y @elgato/mcp-server@latest --verbose
```

This is useful for trying out the server without a permanent installation, or for use in CI/CD environments.

## Usage

### stdio Transport (Default)

For integration with Claude Desktop or other MCP clients using standard I/O:

```bash
elgato-mcp-server
```

### HTTP Transport

For web-based clients or remote access:

```bash
# Start HTTP server on default port (9090)
elgato-mcp-server --http

# Custom port
elgato-mcp-server --http --port 3000

# With ngrok tunnel (requires NGROK_AUTHTOKEN env var)
NGROK_AUTHTOKEN=your_token elgato-mcp-server --http --ngrok
```

### CLI Options

```
Options:
  --transport <mode>  Transport mode: 'stdio' (default) or 'http'
  --http              Shorthand for --transport http
  --port <number>     HTTP server port (default: 9090)
  --ngrok             Enable ngrok tunnel (requires NGROK_AUTHTOKEN env var)
  --help, -h          Show help message
  --verbose, -v       Enable verbose logging (default: silent)
```

### Logging

Logs are written to stderr with a severity label (`ERROR`, `WARN`, `INFO`, `DEBUG`). Errors and warnings always output; info/debug require `--verbose`.

## Claude Desktop Configuration

### Using the Desktop Extension (Recommended)

The easiest way to install is the packaged desktop extension (`.mcpb`), which is fully self-contained and runs on the Node.js runtime included with Claude Desktop — no Node.js, npm, or internet access required:

1. Download the latest `elgato_stream_deck-<version>.mcpb` from the [releases page](https://github.com/elgatosf/elgato-mcp-server/releases).
2. In Claude Desktop, open **Settings → Extensions** and drag the `.mcpb` file into the window (or double-click the file).
3. Make sure the Stream Deck app is running — its tools appear automatically once connected. The built-in `bridge_status` tool reports the connection state at any time.

Alternatively, add the server to your Claude Desktop configuration file manually:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

### Using Global Installation

```json
{
    "mcpServers": {
        "elgato": {
            "command": "elgato-mcp-server"
        }
    }
}
```

### Using npx (No Installation Required)

Alternatively, you can use `npx` to run the server without installing it globally:

```json
{
    "mcpServers": {
        "elgato": {
            "command": "npx",
            "args": ["--yes", "@elgato/mcp-server@latest"]
        }
    }
}
```

> **Note:** The npx-based configuration works with Claude Desktop and other MCP clients that support the stdio transport. The first run may take a moment while npx downloads the package.

## HTTP Endpoints

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

| Endpoint  | Method | Description                            |
| --------- | ------ | -------------------------------------- |
| `/mcp`    | POST   | MCP request endpoint                   |
| `/mcp`    | GET    | Server-Sent Events (SSE) for streaming |
| `/mcp`    | DELETE | Close session                          |
| `/health` | GET    | Health check endpoint                  |

## Requirements

- Elgato app with MCP plugin support (e.g. Stream Deck)
- Node.js 18 or later
- Supported platforms: Windows, macOS

## Privacy Policy

This server runs entirely on your machine and communicates only with locally installed Elgato apps over local IPC (Unix sockets on macOS, named pipes on Windows). It does not collect, store, or transmit personal data to external services. Tool inputs and outputs flow between your MCP client (e.g. Claude Desktop) and the connected Elgato app on the same machine; the optional ngrok tunnel is only established when explicitly enabled with `--ngrok`.

For Elgato/Corsair data handling practices, see the [Elgato Privacy Policy](https://www.elgato.com/en/privacy-policy).

## Contributing

We welcome contributions! For development setup, coding guidelines, and the contribution process, see [CONTRIBUTING.md](https://github.com/elgatosf/elgato-mcp-server/blob/main/CONTRIBUTING.md).

For detailed technical documentation and architecture information, see [TECHNICAL_SPECIFICATION.md](https://github.com/elgatosf/elgato-mcp-server/blob/main/TECHNICAL_SPECIFICATION.md).

## License

MIT License - Copyright (c) Corsair Memory Inc.

See [LICENSE](https://github.com/elgatosf/elgato-mcp-server/blob/main/LICENSE) for details.

## Links

- [GitHub Repository](https://github.com/elgatosf/elgato-mcp-server)
- [npm Package](https://www.npmjs.com/package/@elgato/mcp-server)
- [Issue Tracker](https://github.com/elgatosf/elgato-mcp-server/issues)
- [Elgato](https://www.elgato.com)