Raycast MCP Server

A macOS Model Context Protocol (MCP) server that lets AI assistants invoke nine Raycast and local-automation tools. It uses Raycast URLs, AppleScript, and standard macOS commands, so the automation tools require Raycast on macOS.

Features

Nine registered tools

1. raycast_search - Open Raycast, enter a query, and optionally execute the first result

2. raycast_open - Open a Raycast command or extension URL

3. raycast_clipboard - Show, clear, copy, or paste clipboard content

4. raycast_shortcut - Trigger a predefined Raycast URL or validated keyboard shortcut

5. raycast_window - Show, hide, toggle, or focus Raycast

6. raycast_system - Invoke selected macOS system actions

7. raycast_auth - Audit configured environment credentials, print setup instructions, and validate supported credentials

8. raycast_extensions - Drive supported extension-management flows

9. raycast_workflows - Store and execute local workflow definitions

🚀 Capabilities

• Uses execFile and spawn without shell interpolation

• Validates and length-bounds user-controlled strings

• Uses allowlisted URL schemes and constrained command identifiers

• Supports local workflows, clipboard operations, navigation, and system automation

• Can validate GitHub, Notion, and Figma credentials without returning the credential itself

Authentication scope

This project is not an OAuth callback server and does not exchange authorization codes. The raycast_auth oauth action opens provider authorization URLs, but those templates require you to supply real client IDs and redirect URLs before they are usable. Credential validation is currently implemented for GitHub, Notion, and Figma; other listed services return an explicit “not implemented” result.

Related MCP server: SkyDeckAI Code

Installation

Via Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "raycast": {
      "command": "node",
      "args": ["/path/to/raycast-mcp/dist/index.js"],
      "env": {
        "RAYCAST_API_KEY": "${RAYCAST_API_KEY}",
        "RAYCAST_TEAM_ID": "${RAYCAST_TEAM_ID}"
      }
    }
  }
}

Via NPX

npx raycast-mcp-server@1.0.1

Via Smithery

smithery install raycast-mcp-server

Development

Prerequisites

• Node.js 18+

• macOS with Raycast installed for automation calls

• Accessibility permission for your terminal or MCP host when using AppleScript keyboard control

Setup

git clone https://github.com/ExpertVagabond/raycast-mcp-server.git
cd raycast-mcp-server
npm install
npm run build
npm test

Running Locally

npm start

Building for Production

npm run build

Usage Examples

Authentication Management

# Setup GitHub authentication
{"tool": "raycast_auth", "arguments": {"action": "setup", "service": "github"}}

# Validate credentials  
{"tool": "raycast_auth", "arguments": {"action": "validate", "service": "github"}}

Extension Management

# Search for extensions
{"tool": "raycast_extensions", "arguments": {"action": "search", "query": "github"}}

# List installed extensions
{"tool": "raycast_extensions", "arguments": {"action": "list"}}

Workflow Automation

# Create a custom workflow
{"tool": "raycast_workflows", "arguments": {
  "action": "create",
  "name": "morning-routine",
  "steps": [
    {"type": "command", "action": "open-calendar"},
    {"type": "api_call", "action": "fetch-weather"},
    {"type": "notification", "action": "daily-summary"}
  ]
}}

# Execute a workflow
{"tool": "raycast_workflows", "arguments": {"action": "execute", "name": "morning-routine"}}

Environment variables

• RAYCAST_API_KEY and RAYCAST_TEAM_ID - optional values reported by the credential audit

• GITHUB_TOKEN, NOTION_TOKEN, FIGMA_TOKEN - supported credential validation

• SLACK_TOKEN, LINEAR_TOKEN, JIRA_TOKEN - detected by the audit; remote validation is not implemented

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT

Support

For issues and feature requests, please use the GitHub Issues page.

Built with ❤️ for the Raycast and MCP communities.