# Photon MCP server

> Turns one TypeScript file into CLI tools, MCP servers, and web interfaces that AI clients and humans can invoke.

- Repository: https://github.com/portel-dev/photon
- Page: https://hostedmcp.org/servers/portel-dev/photon
- Transport: stdio
- Stars: 100
- License: MIT

## Install

### Claude Code

```sh
claude mcp add photon -- npx -y @portel/photon
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "photon": {
      "command": "npx",
      "args": [
        "-y",
        "@portel/photon"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "photon": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@portel/photon"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"photon","type":"stdio","command":"npx","args":["-y","@portel/photon"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "photon": {
      "command": "npx",
      "args": [
        "-y",
        "@portel/photon"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add photon -- npx -y @portel/photon
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.photon]
command = "npx"
args = ["-y", "@portel/photon"]
```

### Gemini CLI

```sh
gemini mcp add -s user photon npx -- -y @portel/photon
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "photon": {
      "command": "npx",
      "args": [
        "-y",
        "@portel/photon"
      ]
    }
  }
}
```

## FAQ

### How do I install a Photon tool as an MCP server in Claude Desktop?

Run photon mcp install <name> to register it in Claude Desktop's config, then restart Claude Desktop. Alternatively use photon info <name> --mcp to print a JSON config snippet to paste into an AI client.

### What surfaces can Photon generate from one TypeScript file?

Photon derives an MCP server, an embedded app UI, a CLI tool, a Beam web interface, plus web routes, schedules, webhooks, state, and audit history.

### Does Photon require decorators or server boilerplate?

No. A plain exported TypeScript class with methods is a complete photon; Photon generates CLI, web UI, and MCP server from it.

### What runtime does Photon require?

Photon requires Node.js 20 or later and compiles TypeScript internally, so no tsconfig.json is needed.

### How does Photon validate parameters across interfaces?

A single param tag like @pattern is enforced in the Beam form, the CLI, and the MCP schema at once.
