Gravitino

You run an MCP server that provides Gravitino APIs and a streamlined interface for interacting with metadata. This server lets you manage catalogs, schemas, tables, models, users, tags, and user-role data through FastMCP-enabled tooling, with flexible authentication and tool activation options.

How to use

Start by configuring the MCP server with the environment variables that point to your Gravitino instance and MetalaKe. Run the server in a local development environment, then connect your MCP client to execute metadata operations like listing catalogs, schemas, or managing user roles. You can enable selective tools to limit the available actions and keep token usage efficient.

How to install

Prerequisites: you need Python installed on your system and the uv tool for virtual environments and execution. You will also use git to obtain the MCP server code.

How to install

# Clone the MCP server project
git clone git@github.com:datastrato/mcp-server-gravitino.git

# Move into the project directory
cd mcp-server-gravitino

# Create a virtual environment using uv
uv venv

# Activate the virtual environment
source .venv/bin/activate

# Install dependencies
uv install

Additional sections

Configuration is done through environment variables. The common settings establish your Gravitino target and the metakube to use. You can enable authentication via token or basic username/password, and you can control which tools are active with a single variable.

Additional sections

Key environment variables to set before starting the server: GRAVITINO_URI for the base Gravitino URL and GRAVITINO_METALAKE for the metakube name. Optionally provide GRAVITINO_JWT_TOKEN for token authentication or GRAVITINO_USERNAME and GRAVITINO_PASSWORD for basic authentication. You can also limit active tools by setting GRAVITINO_ACTIVE_TOOLS (default * activates all tools).

Start the MCP server

uv \
  --directory /path/to/mcp-gravitino \
  run \
  --with fastmcp \
  --with httpx \
  --with mcp-server-gravitino \
  python -m mcp_server_gravitino.server

This composite command launches the UV CLI, sets the working directory, runs the managed environment, adds required runtime tools, and starts the Gravitino MCP server via its entry module.

Goose client configuration example

{
  "mcpServers": {
    "Gravitino": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/user/workspace/mcp-server-gravitino",
        "run",
        "--with",
        "fastmcp",
        "--with",
        "httpx",
        "--with",
        "mcp-server-gravitino",
        "python",
        "-m",
        "mcp_server_gravitino.server"
      ],
      "env": {
        "GRAVITINO_URI": "http://localhost:8090",
        "GRAVITINO_USERNAME": "admin",
        "GRAVITINO_PASSWORD": "admin",
        "GRAVITINO_METALAKE": "metalake_demo"
      }
    }
  }
}

Available tools

get_list_of_catalogs

Retrieve a list of catalogs available in the Gravitino metadata store

get_list_of_schemas

Retrieve a list of schemas within a selected catalog

get_list_of_tables

Retrieve a paginated list of tables for a given schema

get_table_by_fqn

Fetch detailed information for a specific table by fully qualified name

get_table_columns_by_fqn

Retrieve column metadata for a specific table

get_list_of_tags

Retrieve all tags defined in the system

associate_tag_to_entity

Attach a tag to a table or column entity

list_objects_by_tag

List objects associated with a particular tag

get_list_of_roles

Retrieve all user roles available in the system

get_list_of_users

Retrieve all users and their metadata

grant_role_to_user

Assign a role to a user

revoke_role_from_user

Revoke a user’s role

get_list_of_models

Retrieve a list of registered models

get_list_of_model_versions_by_fqn

Get versions of a model by its fully qualified name