RayBridge

RayBridge is an MCP server that bridges Raycast extensions to any MCP-compatible client. It discovers locally installed Raycast extensions, loads their tool definitions, and serves them as MCP tools, enabling headless automation and integration with your preferred MCP clients.

How to use

You run RayBridge either as a local process that communicates over stdio or as an HTTP server that remote MCP clients can reach. Start by choosing your transport: use the HTTP server for remote clients or run RayBridge locally to interact through your development setup. Once RayBridge is running, your MCP client can request a list of exposed tools and invoke them by name, supplying the tool input your workflow requires. RayBridge maps each exposed extension’s tools into MCP tools, so you can orchestrate multiple extension functions from a single MCP client.

How to install

Prerequisites you need before installing RayBridge include Bun, Raycast installed with extensions, and sqlcipher for accessing OAuth tokens.

1. Ensure Bun is installed on your system. 2) Install Raycast and verify your extensions are present in Raycast’s extensions directory. 3) Install sqlcipher to access OAuth tokens used by Raycast.

Next, install project dependencies for RayBridge.

bun install

Start the HTTP server (default transport)

You can run RayBridge as an HTTP server to accept remote MCP requests. The default server listens on port 3000 and binds to all interfaces.

bun run start:http

Configure your MCP client to connect to the HTTP server

Provide a client configuration that points to the HTTP endpoint and, if needed, set an API key for authentication. The following example shows the standard configuration pattern used by common clients.

# Example client configuration (HTTP transport)
{
  "mcpServers": {
    "raybridge": {
      "command": "bun",
      "args": ["run", "start:http"],
      "cwd": "/path/to/raybridge"
    }
  }
}

What you can do with RayBridge

RayBridge exposes tools from your Raycast extensions as MCP tools. You can: list available tools, inspect tool details, and call tools with the required input. Tools execute headlessly using Raycast API shims, so you can automate tasks that would normally run inside Raycast’s UI.

Security and access considerations

RayBridge reads OAuth tokens from Raycast’s encrypted database and uses an optional API key for HTTP authentication if you enable it. Tokens are scoped per extension and supplied to tools through the OAuth shim. Tokens may expire; tokens are not refreshed automatically within RayBridge, so ensure your Raycast setup maintains valid credentials.

Configuration and tool exposure

Control which extensions and tools are exposed via a local configuration file at ~/.config/raybridge/tools.json. You can enable or disable extensions and selectively expose tools, choosing between blocklist and allowlist modes.

Notes on the architecture and behavior

RayBridge discovers extensions under your local Raycast configuration, loads their tool definitions, and serves them over MCP. UI components from Raycast are shimmed to no-ops so tools can run headlessly. Non-UI extension logic that performs API calls, data lookups, or transformations will work best in this headless setup.

Troubleshooting tips

If you encounter token or authentication issues, verify your Raycast database access and ensure the OAuth tokens are accessible. If a token has expired, you may need to refresh credentials in Raycast. For HTTP transport issues, confirm the server is running and reachable at the configured host and port.

Available tools

web

Web page reader tool exposed by a Raycast extension. Accepts a URL input and returns the fetched page data for downstream processing.