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:

2. Install dependencies:

3. Build the project:

4. Link globally:

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

Using Docker Hub (Recommended)

1. Pull the latest image from Docker Hub:

2. Run with Docker:

3. Or use Docker Compose:

4. Configure your MCP client:

Building from Source

If you prefer to build from source:

🔧 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:

2. get_data_source

Get details about a specific data source.

Parameters:

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

Example:

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:

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:

🧪 Development

Setup

Testing with act

Test GitHub Actions locally using act:

Project Structure

📦 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