Photon
Define intent once. Photon turns a single TypeScript file into CLI tools, MCP servers, and web interfaces.
What is Photon?
Photon is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to define intent once. photon turns a single typescript file into cli tools, mcp servers, and web interfaces.
Define intent once. Photon turns a single TypeScript file into CLI tools, MCP servers, and web interfaces.
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Define intent once. Photon turns a single TypeScript file in
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx photonConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Photon
Photon is a TypeScript-first development framework that turns a single annotated class or method into multiple deployment surfaces simultaneously: an MCP server for AI agents and tools like Claude Desktop and Cursor, a CLI command, an embedded web UI (called Beam), and HTTP routes with scheduling and webhook support. The core idea is that you define your tool's capability once in a plain TypeScript file — no decorators, no registration boilerplate — and Photon derives all the interfaces and runtime behavior around it. This makes it the fastest path from a verified TypeScript method to a production-ready MCP tool usable by both humans and AI agents.
Prerequisites
- Bun runtime installed (bun.sh) — Photon is installed and run via Bun or pnpm dlx
- Node.js 20+ (if not using Bun)
- TypeScript 5.0+
- An MCP-compatible client such as Claude Desktop, Cursor, or ChatGPT developer mode
Install Photon globally
Install the @portel/photon package globally using Bun (recommended) or pnpm. This makes the photon CLI available system-wide.
bun add -g @portel/photon
# or with pnpm:
pnpm add -g @portel/photonCreate a new photon tool
Run photon new <name> to scaffold a .photon.ts file in your current directory. This is the single file where you define your tool's intent as a plain TypeScript class.
photon new my-toolDefine your tool's capability
Edit the generated .photon.ts file. A minimal photon is just a class with methods. Photon reads JSDoc comments and type signatures to build the MCP tool schema and Beam UI automatically.
// my-tool.photon.ts
export default class MyTool {
/** Greet someone by name */
greet(name: string): string {
return `Hello, ${name}!`;
}
}Install as an MCP server in Claude Desktop
Run photon mcp install <name> to automatically register your photon as an MCP server in Claude Desktop's config file. Restart Claude Desktop after this step.
photon mcp install my-toolOr open the Beam web UI
Run photon (with no arguments) to start Beam, the auto-generated human-facing web interface, and see your tool rendered as a web app at localhost:3008.
photonPhoton Examples
Client configuration
Claude Desktop config for a Photon-generated MCP server. photon mcp install writes this automatically, but you can also add it manually. The command runs the photon CLI in mcp mode for the named tool.
{
"mcpServers": {
"my-tool": {
"command": "bun",
"args": ["/path/to/bun/globals/@portel/photon/bin/photon", "mcp", "my-tool"]
}
}
}Prompts to try
After connecting your Photon tool to Claude Desktop, try these prompts to invoke the methods defined in your .photon.ts file.
- "Use the greet tool to say hello to Alice"
- "List all tools available from the my-tool MCP server"
- "Call the my-tool greet method with name set to 'World'"
- "What methods does the connected photon tool expose?"Troubleshooting Photon
photon command not found after installation
Ensure Bun's global bin directory is in your PATH. Run bun --version to verify Bun is installed, then check that $(bun config get globalBinDir) is in your shell's PATH. You may need to add it to ~/.zshrc or ~/.bashrc and restart your terminal.
Claude Desktop does not show the photon tool after photon mcp install
Restart Claude Desktop fully after running photon mcp install. The MCP config is read at startup. Also verify the config was written correctly by checking ~/Library/Application Support/Claude/claude_desktop_config.json on macOS.
Beam UI does not start or shows an error on port 3008
Another process may be using port 3008. Run lsof -i :3008 to identify it and stop it, then retry photon. Alternatively, check the Photon docs at photon.portel.dev for a flag to specify an alternate port.
Frequently Asked Questions about Photon
What is Photon?
Photon is a Model Context Protocol (MCP) server that define intent once. photon turns a single typescript file into cli tools, mcp servers, and web interfaces. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Photon?
Follow the installation instructions on the Photon GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Photon?
Photon works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Photon free to use?
Yes, Photon is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
Photon Alternatives — Similar Developer Tools Servers
Looking for alternatives to Photon? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Photon in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Photon?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.