Skip to main content
Glama
Malloy MCP Server

Malloy MCP Server

by namabile

Malloy MCP Server

An MCP server implementation for executing Malloy queries and managing Malloy resources.

Features

  • Execute Malloy queries via MCP

  • Access Malloy project, package, and model metadata

  • Robust error handling with detailed context

  • Comprehensive test coverage

  • Type-safe implementation

Related MCP server: Snowflake Cube Server

Installation

# Install using uv (recommended)
uv pip install malloy-mcp-server

# Or using pip
pip install malloy-mcp-server

Usage

Starting the Server

from malloy_mcp_server import mcp

# Run the server
if __name__ == "__main__":
    mcp.serve()

Configuration

The server can be configured using environment variables:

Variable

Description

Default

MALLOY_PUBLISHER_ROOT_URL

URL of the Malloy Publisher API

http://localhost:4000

Example:

# Set the publisher URL
export MALLOY_PUBLISHER_ROOT_URL="http://malloy-publisher:4000"

# Run with custom configuration
python -m malloy_mcp_server

Executing Queries

The server provides an MCP tool for executing Malloy queries:

from malloy_mcp_server import ExecuteMalloyQueryTool

# Example query execution
result = await ExecuteMalloyQueryTool(
    query="select * from users",
    model_path="my_package/users"
)

Accessing Resources

The server provides the following resource endpoints:

  • malloy://project/home/metadata - Project metadata

  • malloy://project/home/package/{package_name} - Package metadata

  • malloy://project/home/model/{model_path} - Model metadata

Development

Setup

  1. Clone the repository:

git clone https://github.com/namabile/malloy-mcp-server.git
cd malloy-mcp-server
  1. Install dependencies:

uv pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=malloy_mcp_server

Code Quality

The project uses:

  • black for code formatting

  • mypy for type checking

  • ruff for linting

Run quality checks:

black .
mypy .
ruff check .

Error Handling

The server provides detailed error handling with context:

from malloy_mcp_server.errors import QueryExecutionError

try:
    result = await ExecuteMalloyQueryTool(...)
except QueryExecutionError as e:
    print(f"Error: {e.message}")
    print("Context:", e.context)

Architecture

The server is built on:

  • FastMCP for the MCP server implementation

  • Malloy Publisher Client for Malloy interactions

  • Pydantic for data validation

Key components:

  • server.py - Core server implementation

  • tools/query_executor.py - Query execution tool

  • errors.py - Error handling utilities

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests for new functionality

  5. Submit a pull request

License

MIT License - see LICENSE file for details

Available Tools

5 tools
execute_malloy_queryA

Execute a Malloy query.

This tool connects to the Malloy Publisher API (default: http://localhost:4000/api/v0)
and executes a Malloy query against a model.

Args:
    project_name: The name of the project, defaults to "home"
    package_name: The name of the package containing the model
    model_path: The path to the model within the package
    query: The Malloy query string to execute (mutually exclusive with query_name)
    source_name: Name of the source in the model (required when using query_name)
    query_name: Name of a query to execute on a source
        (mutually exclusive with query)
    version_id: Version ID of the package

Returns:
    Any: Query execution result with structure:
        {
            "data_styles": Object containing style information
            "model_def": Object containing model definition
            "query_result": Array of result objects
        }

Raises:
    MalloyError: If query execution fails or parameters are invalid
        Error codes:
        - QUERY_EXECUTION_ERROR: Error during query execution
        - CONNECTION_ERROR: Error connecting to Malloy Publisher API

Example:
    ```python
    # Example 1: Direct query
    result = await execute_malloy_query(
        project_name="home",
        package_name="sales",
        model_path="sales.malloy",
        query="query: orders -> { aggregate: count() }"
    )

    # Example 2: Named query
    result = await execute_malloy_query(
        project_name="home",
        package_name="sales",
        model_path="sales.malloy",
        source_name="orders",
        query_name="top_customers"
    )
    ```

Inputs: project_name, package_name, model_path, query, +3 more.

get_modelA

Get details for a specific model.

Args:
    project_name: The name of the project, defaults to "home"
    package_name: The name of the package
    model_path: The path to the model

Returns:
    CompiledModel: The compiled Malloy model

Inputs: project_name, package_name, model_path.

list_modelsA

List models for a package.

Args:
    project_name: The name of the project, defaults to "home"
    package_name: The name of the package to list models for

Returns:
    List[Model]: List of Malloy models

Inputs: project_name, package_name.

list_packagesC

List packages for a project.

Args:
    project_name: The name of the project to list packages for, defaults to "home"

Returns:
    list[Package]: List of Malloy packages

Inputs: project_name.

list_projectsA

List available projects.

This tool doesn't require any input parameters.

Returns:
    list[Project]: List of Malloy projects

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: executing queries, retrieving a specific model, listing models, listing packages, and listing projects. There is no overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow a snake_case verb_noun pattern (e.g., get_model, list_models). The only deviation is execute_malloy_query which uses a two-word noun, but it remains consistent in style.

    Tool Count5/5

    Five tools is well-scoped for a Malloy data exploration server, covering the necessary operations without being too few or too many.

    Completeness4/5

    The toolset covers the core workflow: exploring projects, packages, models, and executing queries. Missing write operations (create/update) are understandable for a query-focused server, but could be considered a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers