# Raycast Integration Guide
This guide shows how to integrate Universal Database MCP Server with Raycast.
## Overview
Raycast is a blazingly fast, totally extendable launcher for macOS. Starting from version 1.98, Raycast supports the Model Context Protocol (MCP), allowing you to connect AI assistants to external tools and data sources. By integrating Universal Database MCP Server, you can enable Raycast's AI to directly query and analyze your database data, making it easier to explore data, generate reports, and get insights without leaving your launcher.
**Key Benefits:**
- Query databases directly from Raycast's AI chat
- Get AI assistance for SQL query writing
- Explore database schema quickly
- Generate data insights on the fly
## Prerequisites
- [Raycast](https://raycast.com/) installed (version 1.98 or later required)
- Raycast Pro subscription (required for AI features)
- Node.js 18+ installed
- Database instance (MySQL, PostgreSQL, SQLite, etc.)
## Configuration
Raycast uses MCP stdio mode for tool integration. Configuration is done through the Raycast settings interface or by importing a JSON configuration file.
### Step 1: Open Raycast Settings
Open Raycast Settings using the keyboard shortcut `Cmd + ,` or by searching for "Settings" in Raycast.
### Step 2: Navigate to MCP Servers
Navigate to **Extensions > AI > MCP Servers** in the settings sidebar.
### Step 3: Add MCP Server Configuration
You can either:
- Click **"Import MCP Servers"** to import a JSON configuration file
- Click **"Add Server"** to manually add a server configuration
#### Import Configuration
Create a JSON file with the following structure and import it:
```json
{
"mcpServers": {
"universal-db-mcp": {
"command": "npx",
"args": [
"universal-db-mcp",
"--type", "mysql",
"--host", "localhost",
"--port", "3306",
"--user", "root",
"--password", "your_password",
"--database", "your_database"
]
}
}
}
```
#### Manual Configuration
If adding manually, enter the following details:
- **Name**: `universal-db-mcp`
- **Command**: `npx`
- **Arguments**: `universal-db-mcp --type mysql --host localhost --port 3306 --user root --password your_password --database your_database`
### Step 4: Enable the Server
After adding the configuration, ensure the MCP server is enabled in the list.
## Configuration Examples
### MySQL
```json
{
"mcpServers": {
"mysql-db": {
"command": "npx",
"args": [
"universal-db-mcp",
"--type", "mysql",
"--host", "localhost",
"--port", "3306",
"--user", "root",
"--password", "your_password",
"--database", "your_database"
]
}
}
}
```
### PostgreSQL
```json
{
"mcpServers": {
"postgres-db": {
"command": "npx",
"args": [
"universal-db-mcp",
"--type", "postgres",
"--host", "localhost",
"--port", "5432",
"--user", "postgres",
"--password", "your_password",
"--database", "your_database"
]
}
}
}
```
### SQLite
```json
{
"mcpServers": {
"sqlite-db": {
"command": "npx",
"args": [
"universal-db-mcp",
"--type", "sqlite",
"--file-path", "/path/to/your/database.db"
]
}
}
}
```
### SQL Server
```json
{
"mcpServers": {
"sqlserver-db": {
"command": "npx",
"args": [
"universal-db-mcp",
"--type", "sqlserver",
"--host", "localhost",
"--port", "1433",
"--user", "sa",
"--password", "your_password",
"--database", "your_database"
]
}
}
}
```
### Oracle
```json
{
"mcpServers": {
"oracle-db": {
"command": "npx",
"args": [
"universal-db-mcp",
"--type", "oracle",
"--host", "localhost",
"--port", "1521",
"--user", "system",
"--password", "your_password",
"--database", "ORCL"
]
}
}
}
```
### MongoDB
```json
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": [
"universal-db-mcp",
"--type", "mongodb",
"--host", "localhost",
"--port", "27017",
"--user", "admin",
"--password", "your_password",
"--database", "your_database"
]
}
}
}
```
### Redis
```json
{
"mcpServers": {
"redis": {
"command": "npx",
"args": [
"universal-db-mcp",
"--type", "redis",
"--host", "localhost",
"--port", "6379",
"--password", "your_password"
]
}
}
}
```
### Multiple Databases
You can configure multiple database connections:
```json
{
"mcpServers": {
"mysql-production": {
"command": "npx",
"args": [
"universal-db-mcp",
"--type", "mysql",
"--host", "prod-db.example.com",
"--port", "3306",
"--user", "readonly_user",
"--password", "prod_password",
"--database", "production_db"
]
},
"mysql-development": {
"command": "npx",
"args": [
"universal-db-mcp",
"--type", "mysql",
"--host", "localhost",
"--port", "3306",
"--user", "root",
"--password", "dev_password",
"--database", "development_db"
]
},
"postgres-analytics": {
"command": "npx",
"args": [
"universal-db-mcp",
"--type", "postgres",
"--host", "analytics-db.example.com",
"--port", "5432",
"--user", "analyst",
"--password", "analytics_password",
"--database", "analytics"
]
}
}
}
```
### Enable Write Operations
By default, write operations are disabled for safety. To enable them:
```json
{
"mcpServers": {
"mysql-db-writable": {
"command": "npx",
"args": [
"universal-db-mcp",
"--type", "mysql",
"--host", "localhost",
"--port", "3306",
"--user", "root",
"--password", "your_password",
"--database", "your_database",
"--allow-write", "true"
]
}
}
}
```
> **Warning**: Enabling write operations allows the AI to execute INSERT, UPDATE, DELETE, and other modifying queries. Use with caution, especially in production environments.
## Available Tools
Once configured, the following MCP tools will be available in Raycast:
| Tool | Description |
|------|-------------|
| `execute_query` | Execute SQL queries against the database |
| `get_schema` | Get database schema information (tables, columns, types) |
| `get_table_info` | Get detailed information about a specific table |
| `clear_cache` | Clear the schema cache |
## Usage Examples
### Example 1: Explore Database Schema
In Raycast's AI chat, you can ask:
```
What tables are in my database?
```
The AI will use the `get_schema` tool to retrieve and display your database structure.
### Example 2: Query Data
Ask the AI to query your data:
```
Show me the last 10 orders from the orders table
```
The AI will generate and execute the appropriate SQL query:
```sql
SELECT * FROM orders ORDER BY created_at DESC LIMIT 10
```
### Example 3: Write SQL Queries
Get help writing complex queries:
```
Write a query to find the top 5 customers by total order value
```
The AI will analyze your schema and generate:
```sql
SELECT
c.id,
c.name,
SUM(o.total_amount) as total_value
FROM customers c
JOIN orders o ON c.id = o.customer_id
GROUP BY c.id, c.name
ORDER BY total_value DESC
LIMIT 5
```
### Example 4: Generate Reports
Ask for quick data summaries:
```
Give me a summary of sales by month for the last year
```
The AI will query your database and provide insights.
### Example 5: Data Analysis
Get AI-powered analysis:
```
Analyze the user signup trends and identify any patterns
```
The AI will examine your data and provide analytical insights.
## Command Line Arguments
| Argument | Required | Description |
|----------|----------|-------------|
| `--type` | Yes | Database type: mysql, postgres, sqlite, sqlserver, oracle, mongodb, redis, dm, kingbase, gaussdb, oceanbase, tidb, clickhouse, polardb, vastbase, highgo, goldendb |
| `--host` | Yes* | Database host |
| `--port` | No | Database port (uses default if not specified) |
| `--user` | Yes* | Database username |
| `--password` | Yes* | Database password |
| `--database` | Yes* | Database name |
| `--file-path` | Yes* | SQLite file path (for sqlite type only) |
| `--allow-write` | No | Enable write operations (default: false) |
| `--oracle-client-path` | No | Oracle Instant Client path (for Oracle 11g) |
*Required fields depend on database type
## Best Practices
### 1. Security
- **Use read-only database users** for production databases
- **Never share** configuration files with real credentials
- **Use environment variables** for sensitive data when possible
- **Limit database permissions** to only what's necessary
### 2. Performance
- Use specific queries instead of `SELECT *`
- Add `LIMIT` clauses to prevent large result sets
- Consider using a read replica for heavy queries
### 3. Workflow
- Configure separate connections for development and production
- Use descriptive names for multiple database connections
- Keep write operations disabled unless specifically needed
## Troubleshooting
### Issue: MCP Server Not Appearing
**Symptoms**: The database tools are not available in Raycast AI
**Solutions**:
1. Verify Raycast version is 1.98 or later
2. Ensure you have a Raycast Pro subscription
3. Check that the MCP server is enabled in Settings > Extensions > AI > MCP Servers
4. Restart Raycast after making configuration changes
### Issue: Connection Refused
**Symptoms**: Error message about connection being refused
**Solutions**:
1. Verify database host and port are correct
2. Check if the database server is running
3. Ensure firewall allows connections to the database port
4. Verify network connectivity to the database host
### Issue: Authentication Failed
**Symptoms**: Error message about invalid credentials
**Solutions**:
1. Double-check username and password
2. Verify the user has permission to access the specified database
3. Check if the database requires SSL/TLS connection
4. Ensure the user can connect from your IP address
### Issue: Permission Denied
**Symptoms**: Queries fail with permission errors
**Solutions**:
1. Verify the database user has SELECT permissions
2. Check if specific tables require additional permissions
3. For write operations, ensure `--allow-write` is set and user has write permissions
### Issue: npx Command Not Found
**Symptoms**: Error indicating npx is not recognized
**Solutions**:
1. Install Node.js (version 18 or later)
2. Ensure Node.js bin directory is in your system PATH
3. Try using the full path to npx
4. Restart Raycast after installing Node.js
### Issue: Server Timeout
**Symptoms**: MCP server takes too long to respond
**Solutions**:
1. Check database server performance
2. Optimize slow queries
3. Ensure stable network connection to the database
4. Consider using a local database for testing
## Resources
- [Raycast Official Website](https://raycast.com/)
- [Raycast Documentation](https://developers.raycast.com/)
- [Raycast MCP Documentation](https://developers.raycast.com/ai/mcp)
- [Universal Database MCP Server Documentation](../README.md)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
## Support
For integration issues:
- GitHub Issues: https://github.com/Anarkh-Lee/universal-db-mcp/issues
- Raycast Community: https://raycast.com/community
