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
- raycast_search - Open Raycast, enter a query, and optionally execute the first result
- raycast_open - Open a Raycast command or extension URL
- raycast_clipboard - Show, clear, copy, or paste clipboard content
- raycast_shortcut - Trigger a predefined Raycast URL or validated keyboard shortcut
- raycast_window - Show, hide, toggle, or focus Raycast
- raycast_system - Invoke selected macOS system actions
- raycast_auth - Audit configured environment credentials, print setup instructions, and validate supported credentials
- raycast_extensions - Drive supported extension-management flows
- 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.
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
Building for Production
Usage Examples
Authentication Management
{"tool": "raycast_auth", "arguments": {"action": "setup", "service": "github"}}
{"tool": "raycast_auth", "arguments": {"action": "validate", "service": "github"}}
Extension Management
{"tool": "raycast_extensions", "arguments": {"action": "search", "query": "github"}}
{"tool": "raycast_extensions", "arguments": {"action": "list"}}
Workflow Automation
{"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"}
]
}}
{"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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- 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.