Skip to main content
Glama
ranger-mcp-server

ranger-mcp-server

by frothkoetter

Ranger MCP Server

Model Context Protocol server for Apache Ranger on CDP — manage access policies, masking, tag-based policies, roles, users, groups, and audit logs via agentic workflows.

Features

  • Knox authentication — JWT token, raw cookie, or Basic Auth (same pattern as Atlas MCP)

  • Policy lifecycle — search, create, update, apply (upsert), delete

  • Access, masking & tag-based policies — convenience builders plus raw JSON for full control

  • Identity management — users, groups, roles and role membership

  • Tag metadata — tag definitions, instances, tagged resources

  • Audit logs — search data-access audits (allowed/denied) and admin/transaction logs (policy changes)

  • Automatic retries — exponential backoff on transient errors

MCP Tools

Services

  • list_ranger_services, get_ranger_service, get_ranger_service_definition

Policies

  • search_ranger_policies, get_ranger_policy, create_ranger_policy, update_ranger_policy, apply_ranger_policy, delete_ranger_policy

  • create_access_policy — resource-based access (Hive/HDFS/etc.)

  • create_masking_policy — column masking

  • create_tag_based_policy — tag-service policies (e.g. cm_tag)

Roles

  • list_ranger_roles, get_ranger_role, create_ranger_role, update_ranger_role, delete_ranger_role

  • add_users_groups_to_role, get_roles_for_user

Users & groups

  • list_ranger_users, get_ranger_user, create_ranger_user, update_ranger_user, delete_ranger_user

  • list_ranger_groups, get_ranger_group, create_ranger_group, update_ranger_group, delete_ranger_group

  • lookup_ranger_users, lookup_ranger_groups

Tags

  • list_tag_definitions, get_tag_definition, list_tag_instances, list_tagged_resources

  • search_tag_based_policies

Audits

  • search_access_audits — data-access audit logs (who accessed what, allowed/denied); filters: request_user, repo_name, resource_path (db/table or db.table), action, access_result, start_date/end_date (MM/DD/YYYY)

  • count_access_audits — count matching access audit records

  • search_admin_audit_logs — policy/config change logs (transaction audit); filters: object_name, action, updated_by, date range

  • count_admin_audit_logs — count matching admin audit records

  • get_admin_audit_log — fetch a single admin audit entry by id

Access audit search defaults to /assets/accessAudit (Ranger UI path), which honors filters on CDP. Set use_assets_endpoint=false to use /xaudit/access_audit instead. Hive table paths use slashes (db/table); db.table is converted automatically.

Related MCP server: zscaler-aiguard-control-plane-mcp

Setup

Local install

git clone <repo-url>
cd ranger-mcp-server
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Cursor / Claude Desktop MCP config

{
  "mcpServers": {
    "ranger-mcp-server": {
      "command": "/FULL/PATH/TO/ranger-mcp-server/.venv/bin/run-server",
      "env": {
        "RANGER_GATEWAY_URL": "https://<host>/<topology>/cdp-proxy-api/ranger/service",
        "RANGER_USER": "<user>",
        "RANGER_PASS": "<password>"
      }
    }
  }
}

uvx

{
  "mcpServers": {
    "ranger-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/frothkoetter/ranger-mcp-server.git@master",
        "run-server"
      ],
      "env": {
        "RANGER_GATEWAY_URL": "https://<host>/<topology>/cdp-proxy-api/ranger/service",
        "RANGER_USER": "<user>",
        "RANGER_PASS": "<password>"
      }
    }
  }
}

Configuration

Variable

Required

Description

RANGER_GATEWAY_URL

Yes

Knox Ranger API base (.../ranger or .../ranger/service; /service is appended automatically if missing)

RANGER_USER / RANGER_PASS

Yes*

Basic auth credentials

KNOX_TOKEN / KNOX_COOKIE

Alt

Knox JWT alternatives

RANGER_VERIFY_SSL

No

Default true

HTTP_TIMEOUT_SECONDS

No

Default 30

* Or Knox token/cookie.

CDP URL pattern

https://<cluster-host>/<topology>/cdp-proxy-api/ranger/service

Direct Ranger Admin (inside cluster): https://<ranger-host>:6182/service

Example agent prompts

  • "List all Ranger services"

  • "Search Hive policies containing 'finance'"

  • "Create a masking policy on column ssn in hr.employees"

  • "Add group analysts to role finance_role"

  • "Show tag-based policies for tag PII on cm_tag"

  • "Search access audits for user alice on cm_hive since 06/01/2026"

  • "Show denied access audits on finance.customers in the last day"

  • "Who changed the finance-read policy? Search admin audit logs"

Troubleshooting MCP server load failures

If CrewAI Agent Studio, Cursor, or another MCP host fails to connect to this server via uvx, check the following.

FastMCP / mcp import error

uvx installs the latest mcp package (currently 2.x). MCP Python SDK 2.0 renamed FastMCP to MCPServer. Older server builds crash on startup with:

ImportError: cannot import name 'FastMCP' from 'mcp.server'

Use a server build that includes the dual-import fix (MCPServer + FastMCP fallback), or pin mcp>=1.28,<2 in your environment.

Verify locally:

RANGER_GATEWAY_URL="https://example.com/ranger/service" \
RANGER_USER="test" RANGER_PASS="test" \
uv run python scripts/test_mcp_stdio.py uvx --from . run-server

Expected output: OK initialize and OK tools/list: 41 tools.

Missing Ranger credentials at startup

The server requires RANGER_GATEWAY_URL in the MCP host's env block. If it is missing, startup fails before the MCP handshake:

ValueError: RANGER_GATEWAY_URL must be set.

Set RANGER_USER / RANGER_PASS (or KNOX_TOKEN / KNOX_COOKIE) for authenticated Ranger API calls after the server starts.

Agent Studio / CrewAI config

Recommended MCP config (stdio transport is the default for run-server):

{
  "mcpServers": {
    "ranger-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/frothkoetter/ranger-mcp-server.git@master",
        "run-server"
      ],
      "env": {
        "RANGER_GATEWAY_URL": "https://<host>/<topology>/cdp-proxy-api/ranger/service",
        "RANGER_USER": "<username>",
        "RANGER_PASS": "<password>"
      }
    }
  }
}

Ensure uvx is on the Agent Studio host PATH (which uvx).

License

Apache License 2.0

Available Tools

36 tools
add_users_groups_to_roleC

Add users and/or groups to an existing role. WRITE OPERATION

Inputs: role_id (required), users, groups. Returns: result

apply_ranger_policyC

Create or update a policy via the apply/upsert endpoint. WRITE OPERATION

Inputs: policy_json (required). Returns: result

create_access_policyC

Create an access-control policy. WRITE OPERATION

Provide resources via resources_json or simple fields (database, table, column, path). users/groups/roles/accesses are comma-separated.

Inputs: service_name (required), policy_name (required), users, groups, +8 more. Returns: result

create_masking_policyB

Create a data-masking policy (policyType=1). WRITE OPERATION

data_mask_type examples: MASK, MASK_SHOW_LAST_4, MASK_HASH, MASK_NULL, CUSTOM.

Inputs: service_name (required), policy_name (required), data_mask_type (required), users, +7 more. Returns: result

create_ranger_groupC

Create a Ranger group. WRITE OPERATION

Inputs: group_name (required), description. Returns: result

create_ranger_policyC

Create a Ranger policy from a full JSON payload. WRITE OPERATION

Inputs: policy_json (required). Returns: result

create_ranger_roleC

Create a Ranger role with optional members. WRITE OPERATION

Inputs: role_name (required), description, users, groups, +1 more. Returns: result

create_ranger_userB

Create a Ranger user. WRITE OPERATION

user_roles: ROLE_USER or ROLE_SYS_ADMIN. group_ids: comma-separated numeric ids.

Inputs: user_name (required), password, first_name, last_name, +2 more. Returns: result

create_tag_based_policyB

Create a tag-based access policy on the tag service (e.g. cm_tag). WRITE OPERATION

access_type is prefixed by target service, e.g. hive:select or hdfs:read.

Inputs: tag_service_name (required), policy_name (required), tag_name (required), access_type (required), +3 more. Returns: result

delete_ranger_groupB

Delete a Ranger group by id. WRITE OPERATION

Inputs: group_id (required).

delete_ranger_policyC

Delete a policy by id or by service_name + policy_name. WRITE OPERATION

Inputs: policy_id, service_name, policy_name.

delete_ranger_roleC

Delete a Ranger role by id. WRITE OPERATION

Inputs: role_id (required).

delete_ranger_userB

Delete a Ranger user by id. WRITE OPERATION

Inputs: user_id (required).

get_ranger_groupB

Get a Ranger group by name.

Inputs: group_name (required). Returns: result

get_ranger_policyA

Get a policy by id or by service_name + policy_name.

Inputs: policy_id, service_name, policy_name. Returns: result

get_ranger_roleB

Get a role by id or name.

Inputs: role_id, role_name. Returns: result

get_ranger_serviceB

Get a Ranger service instance by name.

Inputs: service_name (required). Returns: result

get_ranger_service_definitionA

Get the service definition schema (access types, resources, mask types) for a component type.

Inputs: service_type (required). Returns: result

get_ranger_userB

Get a Ranger user by name.

Inputs: user_name (required). Returns: result

get_roles_for_userC

List roles assigned to a user.

Inputs: user_name (required).

get_tag_definitionB

Get a tag definition by name.

Inputs: tag_name (required). Returns: result

list_ranger_groupsC

List Ranger groups.

Inputs: page_size, start_index.

list_ranger_rolesC

List Ranger policy-engine roles.

Inputs: page_size, start_index.

list_ranger_servicesC

List Ranger service instances (cm_hive, cm_hdfs, cm_tag, etc.).

Inputs: page_size, start_index, service_name, service_type.

list_ranger_usersC

List Ranger users.

Inputs: page_size, start_index.

list_tag_definitionsB

List Ranger tag type definitions.

Inputs: no named parameters.

list_tagged_resourcesC

List resources that have tags applied.

Inputs: service_name.

list_tag_instancesC

List tag instances in Ranger.

Inputs: no named parameters.

lookup_ranger_groupsB

Search Ranger groups by partial name.

Inputs: name (required).

lookup_ranger_usersC

Search Ranger users by partial name.

Inputs: name (required).

search_ranger_policiesC

Search Ranger policies. policy_type: 0=access, 1=masking, 2=row-filter.

Inputs: service_name, policy_name, policy_name_partial, user, +4 more.

search_tag_based_policiesC

Search tag-based policies on the tag service (e.g. cm_tag).

Inputs: tag_service_name (required), tag_name, page_size, start_index.

update_ranger_groupC

Update a Ranger group from JSON. WRITE OPERATION

Inputs: group_id (required), group_json (required). Returns: result

update_ranger_policyC

Update an existing Ranger policy by id. WRITE OPERATION

Inputs: policy_id (required), policy_json (required). Returns: result

update_ranger_roleC

Update a Ranger role from JSON. WRITE OPERATION

Inputs: role_id (required), role_json (required). Returns: result

update_ranger_userC

Update a Ranger user from JSON. WRITE OPERATION

Inputs: user_id (required), user_json (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 36 tools

    Disambiguation4/5

    Most tools have distinct purposes (CRUD for users, groups, roles, policies, services, tags). However, there is overlap between create_access_policy, create_ranger_policy, and apply_ranger_policy, which could confuse an agent selecting the right one for a given task.

    Naming Consistency3/5

    Majority follow verb_noun pattern (create_ranger_user, get_ranger_group, list_ranger_users), but there are deviations like add_users_groups_to_role, apply_ranger_policy, lookup_ranger_groups, and mixing list/search/lookup for similar operations reduces consistency.

    Tool Count3/5

    36 tools is high but covers multiple resource types (users, groups, roles, policies, services, tags). Some tools could be merged (e.g., list/search variants) to reduce count. Not extreme, but borderline heavy for typical agent interactions.

    Completeness3/5

    Covers CRUD for users, groups, roles, and access/masking policies. Missing create/update/delete for tag definitions and tag-based resources, and row-filter policy lifecycle (only searchable). Gaps will require workarounds.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables governed agent access to Cortex XSIAM security operations APIs, including XQL log search, issues, cases, endpoints, and assets, with dataset authorization and optional identity-based access control.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to access registered resources based on a fixed subject identity, enforcing default-deny policies and auditing for controlled context sharing.
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables governed remote execution of Hermes Agent tasks over MCP with client authentication, RBAC, audit logging, and human-in-the-loop approvals.
      -