coalesce-mcp 0.2.0

MCP server for Coalesce data pipeline investigation

Coalesce MCP Server

A Model Context Protocol (MCP) server for investigating Coalesce data pipeline failures interactively with Claude.

Overview

This MCP server provides tools to investigate Coalesce job runs, making it easy for data engineers to diagnose pipeline failures directly in Claude Desktop or Claude.ai. Ask Claude about your Coalesce pipelines in natural language and get detailed error analysis, node-level results, and actionable recommendations.

What you can do:

• List recent job runs and failures
• Get detailed error messages for failed runs
• Investigate node-level execution results
• Understand what SQL was executed
• Identify root causes of pipeline failures

All operations are read-only - no jobs are triggered or modified.

Installation

Using pip

pip install coalesce-mcp

Using uv (recommended)

uv tool install coalesce-mcp

Configuration

Get Your Coalesce API Token

1. Log into Coalesce
2. Go to Settings → API Tokens
3. Create a new token with read access
4. Copy the token (you'll need it for configuration)

Configure Claude Desktop

Using uvx (Recommended)

uvx provides isolated environments and is the recommended way to run MCP servers.

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "coalesce": {
      "command": "uvx",
      "args": ["--from", "coalesce-mcp", "coalesce-mcp-server"],
      "env": {
        "COALESCE_API_TOKEN": "your-api-token-here",
        "COALESCE_BASE_URL": "https://app.coalescesoftware.io/api"
      }
    }
  }
}

Using uv tool install

First install the tool:

uv tool install coalesce-mcp

Then configure Claude Desktop:

{
  "mcpServers": {
    "coalesce": {
      "command": "coalesce-mcp-server",
      "env": {
        "COALESCE_API_TOKEN": "your-api-token-here",
        "COALESCE_BASE_URL": "https://app.coalescesoftware.io/api"
      }
    }
  }
}

Using pip/pipx

First install globally:

# Using pip
pip install coalesce-mcp

# Or using pipx (isolated)
pipx install coalesce-mcp

Then use the same configuration as "uv tool install" above

Restart Claude Desktop

After updating the configuration, restart Claude Desktop to load the MCP server.

Available Tools

The server provides 6 tools for investigating Coalesce job runs:

1. list_job_runs

Lists recent job runs with optional filters.

Parameters:

• environment_id (optional): Filter by environment ID
• run_status (optional): Filter by status - running, completed, failed, canceled
• limit (optional): Maximum number of runs to return (default 50)
• starting_from (optional): Cursor for pagination

Example prompts:

• "Show me recent Coalesce runs"
• "List all completed runs from the last week"

2. list_failed_runs

Convenience tool that filters for failed runs only.

Parameters:

• environment_id (optional): Filter by environment ID
• limit (optional): Maximum number of failed runs (default 20)
• starting_from (optional): Cursor for pagination

Example prompts:

• "What jobs have failed recently?"
• "Show me all failed runs"

3. get_run

Gets full details for a specific run.

Parameters:

• run_id (required): The ID of the run to retrieve

Example prompts:

• "Get details for run 79458"
• "Show me information about run 12345"

4. get_run_status

Gets the current status of a run.

Parameters:

• run_id (required): The ID of the run to check

Example prompts:

• "Is run 79458 still running?"
• "What's the status of run 12345?"

5. get_run_results

Gets node-level execution results.

Parameters:

• run_id (required): The ID of the run to get results for

Example prompts:

• "Show me which nodes failed in run 79458"
• "What are the execution results for run 12345?"

6. get_job_details (RECOMMENDED)

Combines all information about a run in one call - status, results, and extracted error details.

Parameters:

• run_id (required): The ID of the run to investigate

Example prompts:

• "Investigate failure in run 79458"
• "What went wrong with run 12345?"
• "Analyze run 79458 and explain the error"

Usage Examples

Once installed and configured, you can ask Claude questions like:

"Can you list recent failed Coalesce runs?"

"What went wrong with run 79458?"

"Show me the error messages from the latest failed run"

"Which nodes failed in run 79458 and what were the error messages?"

"Investigate the most recent failure and explain what happened"

"List all runs from the production environment"

Claude will use the appropriate tools to answer your questions and provide detailed analysis.

Requirements

• Python: 3.10 or higher
• Coalesce account: With API access
• API token: Read access to job runs

Security

• API tokens are environment variables - never hardcoded
• Each user provides their own token - decentralized authentication
• Read-only operations - no jobs are triggered or modified
• No logging of credentials - tokens are kept secure

Troubleshooting

Known Issues

Version 0.1.2 is broken. If you installed version 0.1.2, you'll see ModuleNotFoundError: No module named 'coalesce_mcp'. Upgrade to version 0.1.3 or later:

# Using uvx (recommended)
uvx coalesce-mcp@latest

# Using pip
pip install --upgrade coalesce-mcp

# Using uv tool
uv tool upgrade coalesce-mcp

Verify Installation

After installation, verify it's working correctly:

# Check version (should be 0.1.3 or later)
python -c "import coalesce_mcp; print(coalesce_mcp.__version__)"

# Verify command exists
coalesce-mcp-server --help

If the import fails, you may have the broken 0.1.2 version - upgrade using the commands above.

MCP Server Not Detected

1. Verify the configuration path is correct for your OS
2. Check that the JSON is valid (no trailing commas)
3. Restart Claude Desktop after configuration changes
4. Check Claude Desktop logs for error messages

Authentication Errors

1. Verify your API token is correct
2. Check that the token has read access to job runs
3. Ensure COALESCE_BASE_URL is set correctly

Command Not Found

If coalesce-mcp-server command is not found:

# Using uvx (recommended)
uvx coalesce-mcp

# Using pip
pip install --force-reinstall coalesce-mcp

# Using uv tool
uv tool install --force coalesce-mcp

Development

To contribute or modify the server:

# Clone the repository
git clone https://github.com/yourusername/coalesce-mcp.git
cd coalesce-mcp

# Install dependencies
pip install -e .

# Run tests
pytest

License

MIT License - see LICENSE file for details

Support

• Issues: https://github.com/JarredR092699/coalesce-mcp/issues
• Coalesce API Docs: https://docs.coalesce.io/docs/api

Credits

Built with the Model Context Protocol for Claude AI integration.