Polaris Catalog & Iceberg Governance Server

A FastMCP server that gives AI assistants (and data engineers) conversational access to Apache Polaris catalog management, Iceberg REST Catalog APIs, and PyIceberg table storage/health inspection tools.

It is designed to enable AI agents (like Cursor, Windsurf, or Claude Desktop) to audit data governance, check access control roles, query namespaces, and inspect Iceberg metadata.

---

What it does

12 tools across 10 categories:

Category	Tool Name	Operations	What you can ask
Connection	connect	N/A	"Connect to Polaris"
	disconnect	N/A	"Disconnect from the Polaris server"
	get_server_config	N/A	"What endpoints does the server support?"
Catalogs	catalog_request	list, get	"What catalogs exist?", "Show me the storage config for catalog X"
Namespaces	namespace_request	list, get, exists	"List all namespaces in catalog X", "Does namespace Y exist?"
Tables	table_request	list, get, exists	"List tables in prod.analytics", "Show me the schema and snapshots for table Z"
Views	view_request	list, get, exists	"List views", "Load the revenue_daily view metadata"
Principals	principal_request	list, get, roles_assigned	"Who has access?", "What roles does Alice have?"
Roles & Grants	role_request	list_principal_roles, get_principal_role, list_principals_for_role, list_catalog_roles, get_catalog_role, list_catalog_roles_for_principal_role, list_principal_roles_for_catalog_role, list_grants_for_catalog_role	"What roles exist?", "Which catalog roles map to service_admin?", "What privileges does the analyst role have?"
Policies	policy_request	list, get, get_applicable	"What policies apply to this table?", "Show the compaction policy"
Generic Tables	generic_table_request	list, get	"What Delta/CSV tables are registered?"
Metadata Inspection	inspect_request	snapshots, files, manifests, partitions, health	"Check snapshot history", "List raw Parquet data/delete files", "Show partition health/delete file overhead"

---

Quick Start

Install

cd apache-polaris-iceberg-ai-mcp
pip install -e .

Run the server

# Via FastMCP CLI
fastmcp run server.py

# Or directly
python -m server

Configure in Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "polaris-catalog": {
      "command": "fastmcp",
      "args": ["run", "/path/to/apache-polaris-iceberg-ai-mcp/server.py"]
    }
  }
}

Configure in VS Code (Copilot / Cline / etc.)

Add to your .vscode/mcp.json or MCP settings:

{
  "servers": {
    "polaris-catalog": {
      "command": "fastmcp",
      "args": ["run", "/path/to/apache-polaris-iceberg-ai-mcp/server.py"]
    }
  }
}

---

Authentication

The server supports three authentication modes via the connect tool:

1. Client Credentials (default)

connect(uri="http://localhost:8181", client_id="admin", client_secret="password")

2. Bearer Token

connect(uri="http://localhost:8181", token="eyJhbGciOiJSUzI1NiIs...")

3. Keycloak / OIDC Password Credentials

Use this to exchange username/password credentials for a token from Keycloak or another OIDC provider first, and then authenticate to Polaris with that token:

connect(
  uri="http://localhost:8181",
  oauth_token_url="http://localhost:8080/realms/polaris-realm/protocol/openid-connect/token",
  client_id="polaris-client",
  client_secret="sBbUvTG7qWGbmgwgxKmnEuzqpuE3uGAu",
  username="sankeerth",
  password="nagapuri"
)

---

Storage & Inspection Configuration

Since the inspect_request tool reads the underlying Avro metadata and Parquet data/delete files directly from your object storage, you should configure your S3/MinIO environment variables or pass options dynamically.

S3 / MinIO Environment Variables

By default, the inspection tools look for these environment variables or fallback to local MinIO dev defaults (admin / password / http://localhost:9000):

• S3_ENDPOINT: S3 endpoint URL (e.g., http://localhost:9000 or https://s3.amazonaws.com)
• AWS_ACCESS_KEY_ID: Your AWS or MinIO access key
• AWS_SECRET_ACCESS_KEY: Your AWS or MinIO secret key

Override parameters

The inspect_request tool also accepts optional overrides:

• s3_endpoint
• aws_access_key_id
• aws_secret_access_key

---

Architecture

apache-polaris-iceberg-ai-mcp/
├── server.py              # FastMCP server — registers consolidated tools
├── client.py              # Async HTTP client (httpx) with OAuth2 + password grant auth
├── requirements.txt       # Dependencies (fastmcp, httpx, pydantic, pyiceberg, pyarrow, s3fs)
└── tools/                 # Tool implementations by domain
    ├── connection.py      # connect, disconnect, get_server_config
    ├── catalogs.py        # catalog_request (list, get)
    ├── principals.py      # principal_request (list, get, roles_assigned)
    ├── roles.py           # role_request (principal/catalog roles, mapping, grants)
    ├── namespaces.py      # namespace_request (list, get, exists)
    ├── tables.py          # table_request (list, get, exists)
    ├── views.py           # view_request (list, get, exists)
    ├── policies.py        # policy_request (list, get, get_applicable)
    ├── generic_tables.py  # generic_table_request (list, get)
    └── inspect.py         # inspect_request (snapshots, files, manifests, partitions, health)

---

License

MIT License