Explore and Govern Data Metadata

MCP Server for Apache Gravitino

MCP server providing Gravitino APIs - A FastMCP integration for Apache Gravitino services.

Features

• Seamless integration with FastMCP for Gravitino APIs
• Simplified interface for metadata interaction
• Supports metadata operations for catalogs, schemas, tables, models, users, tags, and user-role management

Installation

This project uses uv as the dependency and virtual environment management tool. Please ensure uv is installed on your system.

1. Clone the repository:

   git clone git@github.com:datastrato/mcp-server-gravitino.git
   

2. Navigate into the project directory:

   cd mcp-server-gravitino
   

3. Create a virtual environment:

   uv venv
   

4. Activate the virtual environment:

   source .venv/bin/activate
   

5. Install dependencies:

   uv install
   

Configuration

Common Configuration

Regardless of the Authorization, the following environment variables need to be set:

GRAVITINO_METALAKE=<YOUR_METALAKE> # default: "metalake_demo"
GRAVITINO_URI=<YOUR_GRAVITINO_URI>

• GRAVITINO_URI: The base URL of your Gravitino server.
• GRAVITINO_METALAKE: The name of the metakube to use.

Authorization

mcp-server-gravitino supports both token-based and basic authentication methods. These mechanisms allow secure access to MCP tools and prompts and are suitable for integration with external systems.

Token Authentication

Set the following environment variables:

GRAVITINO_JWT_TOKEN=<YOUR_GRAVITINO_JWT_TOKEN>

GRAVITINO_JWT_TOKEN: The JWT token for authentication.

Basic Authentication

Alternatively, you can use basic authentication:

GRAVITINO_USERNAME=<YOUR_GRAVITINO_USERNAME>
GRAVITINO_PASSWORD=<YOUR_GRAVITINO_PASSWORD>

• GRAVITINO_USERNAME: The username for Gravitino authentication.
• GRAVITINO_PASSWORD: The corresponding password.

Tool Activation

Tool activation is currently based on method names (e.g., get_list_of_table). You can specify which tools to activate by setting the optional environment variable GRAVITINO_ACTIVE_TOOLS. The default value is *, which activates all tools. If just want to activate get_list_of_roles tool, you can set the environment variable as follows:

GRAVITINO_ACTIVE_TOOLS=get_list_of_roles

Usage

To launch the Gravitino MCP Server, run the following command:

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

The meaning of each argument is as follows:

Argument	Description
uv	Launches the UV CLI tool
--directory /path/to/mcp-gravitino	Specifies the working project directory with pyproject.toml
run	Indicates that a command will be executed in the managed environment
--with fastmcp	Adds fastmcp to the runtime environment without altering project deps
--with httpx	Adds httpx dependency for async HTTP functionality
--with mcp-server-gravitino	Adds the local module as a runtime dependency
python -m mcp_server_gravitino.server	Starts the MCP server using the package's entry module

Goose Client Example

Example configuration to run the server using Goose:

{
  "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"
      }
    }
  }
}

Tool List

mcp-server-gravitino does not expose all Gravitino APIs, but provides a selected set of optimized tools:

Table Tools

• get_list_of_catalogs: Retrieve a list of catalogs
• get_list_of_schemas: Retrieve a list of schemas
• get_list_of_tables: Retrieve a paginated list of tables
• get_table_by_fqn: Fetch detailed information for a specific table
• get_table_columns_by_fqn: Retrieve column information for a table

Tag Tools

• get_list_of_tags: Retrieve all tags
• associate_tag_to_entity: Attach a tag to a table or column
• list_objects_by_tag: List objects associated with a specific tag

User Role Tools

• get_list_of_roles: Retrieve all roles
• get_list_of_users: Retrieve all users
• grant_role_to_user: Assign a role to a user
• revoke_role_from_user: Revoke a user's role

Model Tools

• get_list_of_models: Retrieve a list of models
• get_list_of_model_versions_by_fqn: Get versions of a model by fully qualified name

Each tool is designed to return concise and relevant metadata to stay within LLM token limits while maintaining semantic integrity.