# Apache Polaris Iceberg Ai Mcp

> Model Context Protocol (MCP) server for Apache Polaris. Enables AI agents and LLMs to interact with Polaris Catalog Management, audit data governance and access control (RBAC) policies, and perform Iceberg table inspections using PyIceberg.

- **Type:** MCP server
- **Install:** `agentstack add mcp-sankeerthnagapuri-apache-polaris-iceberg-ai-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sankeerthnagapuri](https://agentstack.voostack.com/s/sankeerthnagapuri)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sankeerthnagapuri](https://github.com/sankeerthnagapuri)
- **Source:** https://github.com/sankeerthnagapuri/apache-polaris-iceberg-ai-mcp

## Install

```sh
agentstack add mcp-sankeerthnagapuri-apache-polaris-iceberg-ai-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Polaris Catalog & Iceberg Governance MCP Server

A [FastMCP](https://github.com/jlowin/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

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

### Run the server

```bash
# Via FastMCP CLI
fastmcp run server.py

# Or directly
python -m server
```

### Configure in Claude Desktop

Add to your `claude_desktop_config.json`:

```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:

```json
{
  "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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sankeerthnagapuri](https://github.com/sankeerthnagapuri)
- **Source:** [sankeerthnagapuri/apache-polaris-iceberg-ai-mcp](https://github.com/sankeerthnagapuri/apache-polaris-iceberg-ai-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sankeerthnagapuri-apache-polaris-iceberg-ai-mcp
- Seller: https://agentstack.voostack.com/s/sankeerthnagapuri
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.