Redash MCP Server

A Model Context Protocol (MCP) server for Redash that provides query execution, data source management, and more through a standardized interface.

✨ Features

• 🔍 Query Execution: Execute SQL queries and retrieve results

• 📊 Data Source Management: List and inspect data sources

• 🔐 Secure: API key-based authentication

• 🐳 Docker Support: Easy deployment with Docker

• ✅ Fully Tested: Comprehensive test coverage with TDD approach

• 🚀 Modern Stack: Built with TypeScript, Vite, and latest tooling

📋 Requirements

• Node.js: >= 22.0.0

• pnpm: >= 9.0.0

• Redash Instance: With API access

• Docker (optional): For containerized deployment

🚀 Quick Start

Using npx (Recommended)

1. Clone the repository:

git clone https://github.com/jasonsmithj/redash-mcp.git
cd redash-mcp

2. Install dependencies:

pnpm install

3. Build the project:

pnpm build

4. Link globally:

pnpm link

5. Configure your MCP client (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "redash": {
      "command": "npx",
      "args": ["redash-mcp"],
      "env": {
        "REDASH_API_KEY": "your_api_key_here",
        "REDASH_BASE_URL": "https://redash.example.com"
      }
    }
  }
}

Using Docker Hub (Recommended)

1. Pull the latest image from Docker Hub:

docker pull jasonsmithj/redash-mcp:latest

2. Run with Docker:

docker run -i --rm \
  -e REDASH_API_KEY=your_api_key \
  -e REDASH_BASE_URL=https://redash.example.com \
  jasonsmithj/redash-mcp:latest

3. Or use Docker Compose:

# Create .env file
cp .env.example .env
# Edit .env with your credentials

# Start the service
docker compose up

4. Configure your MCP client:

{
  "mcpServers": {
    "redash": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "REDASH_API_KEY",
        "-e",
        "REDASH_BASE_URL",
        "jasonsmithj/redash-mcp:latest"
      ],
      "env": {
        "REDASH_API_KEY": "your_api_key_here",
        "REDASH_BASE_URL": "https://redash.example.com"
      }
    }
  }
}

Building from Source

If you prefer to build from source:

docker build -t redash-mcp:local .

🔧 Configuration

Environment Variables

Getting Your Redash API Key

1. Log in to your Redash instance

2. Click on your profile icon → "Edit Profile"

3. Copy your API key from the "API Key" section

🛠 Available Tools

1. list_data_sources

List all available data sources in Redash.

Parameters: None

Example:

List all data sources

2. get_data_source

Get details about a specific data source.

Parameters:

• data_source_id (number): The ID of the data source

Example:

Get details for data source 1

3. execute_query_and_wait

Execute a SQL query and wait for the result.

Parameters:

• query (string): The SQL query to execute

• data_source_id (number): The ID of the data source

• max_age (number, optional): Maximum age of cached results in seconds

Example:

Execute query "SELECT * FROM users LIMIT 10" on data source 1

4. list_queries

List all queries in Redash.

Parameters:

• page (number, optional): Page number (default: 1)

• page_size (number, optional): Results per page (default: 25)

Example:

List all queries

🧪 Development

Setup

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests with UI
pnpm test:ui

# Run tests with coverage
pnpm test:coverage

# Type check
pnpm typecheck

# Lint
pnpm lint

# Format code
pnpm format

# Run all checks (CI equivalent)
pnpm ci

Testing with act

Test GitHub Actions locally using act:

# List available workflows
act -l

# Run CI workflow
act push

# Run specific job
act -j quality

Project Structure

redash-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── redash-client.ts      # Redash API client
│   ├── types.ts              # Type definitions
│   └── tools/                # MCP tools
│       ├── datasource.ts     # Data source tools
│       └── query.ts          # Query execution tools
├── tests/                    # Test files
├── scripts/                  # Build scripts
├── .github/
│   └── workflows/            # GitHub Actions CI/CD
├── Dockerfile                # Docker configuration
├── compose.yaml              # Docker Compose configuration
└── package.json

📦 Scripts

• pnpm dev: Watch mode for development

• pnpm build: Build for production

• pnpm test: Run tests

• pnpm test:coverage: Run tests with coverage report

• pnpm lint: Lint code

• pnpm format: Format code

• pnpm ci: Run all quality checks

🏗 Tech Stack

• Runtime: Node.js 22+ with ES Modules

• Language: TypeScript 5.7+ (strict mode)

• Build Tool: Vite 6.x

• Package Manager: pnpm 9.x

• Testing: Vitest 3.x with coverage

• Linting: ESLint 9.x (Flat Config)

• Formatting: Prettier 3.x

• MCP SDK: @modelcontextprotocol/sdk 1.x

📦 Docker Images

Pre-built Docker images are available on Docker Hub:

• Latest stable: jasonsmithj/redash-mcp:latest

• Specific version: jasonsmithj/redash-mcp:v1.0.0

• Major version: jasonsmithj/redash-mcp:1

Supported Platforms

Multi-architecture images are automatically built for both platforms:

• linux/amd64 (x86_64) - Intel/AMD CPUs

  • Windows PCs

  • Intel-based Macs

  • Traditional Linux servers

• linux/arm64 (ARM64) - ARM CPUs

  • Apple Silicon Macs (M1/M2/M3/M4)

  • ARM-based Linux servers

  • Raspberry Pi 4+ (64-bit)

Docker will automatically pull the correct image for your platform!

🚀 Releasing

To release a new version:

1. Update version in package.json

2. Commit changes: git commit -am "chore: bump version to vX.Y.Z"

3. Create and push tag: git tag vX.Y.Z && git push origin vX.Y.Z

4. GitHub Actions will automatically build and push to Docker Hub

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Make your changes and add tests

4. Run quality checks: pnpm ci

5. Commit your changes: git commit -m 'Add amazing feature'

6. Push to the branch: git push origin feature/amazing-feature

7. Open a Pull Request

Development Guidelines

• Follow TDD (Test-Driven Development) approach

• Write tests before implementation

• Maintain test coverage above 85%

• Use conventional commits

• Add JSDoc comments for public APIs

• All code comments should be in English

Setting up GitHub Secrets for CD

To enable automated Docker Hub publishing, add the following secrets to your GitHub repository:

1. Go to Settings → Secrets and variables → Actions

2. Add the following secrets:

   • DOCKER_USERNAME: Your Docker Hub username

   • DOCKER_PASSWORD: Your Docker Hub password or access token

For enhanced security, use a Docker Hub access token instead of your password:

1. Log in to Docker Hub

2. Go to Account Settings → Security → New Access Token

3. Generate a token with "Read, Write, Delete" permissions

4. Use this token as DOCKER_PASSWORD

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📮 Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions

Made with ❤️ by the Redash MCP community