Grouper MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Internet2's Grouper identity management system via web services.

Features

This MCP server provides 22 core tools for essential Grouper operations, organized into six main categories:

• Group Management (8 tools) - Search, create, retrieve, update, and delete groups (including composite groups with UNION, INTERSECTION, and COMPLEMENT operations)
• Stem/Folder Management (3 tools) - Search and browse organizational hierarchy
• Member Management (4 tools) - Add, remove, list group members, and trace membership paths
• Privilege Management (2 tools) - Grant, revoke, and query privileges on groups and stems
• Attribute Management (1 tool) - Assign attributes to groups
• Subject Management (4 tools) - Search for and retrieve information about subjects and their group memberships

For detailed documentation of all available tools, parameters, and usage examples, see TOOLS.md.

This implementation covers the essential group lifecycle and membership management operations that handle most common use cases. Many additional Grouper web service endpoints are not yet implemented but are planned - see the TODO.md for the complete list of planned features.

Configuration

The server supports configuration via environment variables or properties files. Key environment variables:

• GROUPER_BASE_URL (required): Full URL to Grouper web services endpoint
• GROUPER_USERNAME (required): Grouper authentication username
• GROUPER_PASSWORD (required): Grouper authentication password
• READ_ONLY: Enable read-only mode ("true" or "false")
• GROUPER_DEBUG: Enable detailed debug logging ("true" or "false")
• NODE_TLS_REJECT_UNAUTHORIZED: Set to "0" for self-signed certificates (development only)

For complete configuration details including properties files, read-only mode, logging, TLS/SSL, and act-as configuration, see Configuration Guide.

Installation

Option 1: Docker Installation (Recommended)

Standard stdio MCP Server

For use with Claude Desktop or other MCP clients that support stdio:

# Clone this repository
git clone <repository-url>
cd grouper-mcp

# Build the Docker image
docker build -t grouper-mcp:latest .

HTTP-Enabled Server (with MCPO)

For HTTP/SSE access (Open WebUI, web-based AI agents, etc.):

# Clone this repository
git clone <repository-url>
cd grouper-mcp

# Build the HTTP-enabled Docker image
docker build -f Dockerfile.http -t grouper-mcp:http .

This image includes both the MCP server and MCPO proxy, providing instant HTTP access without additional setup.

Option 2: Local Installation

For development or custom deployments:

1. Clone this repository

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Usage

Local Development

Run in development mode with:

npm run dev

Local Production

Build and run:

npm run build
npm start

With Claude Desktop

Once you've built the Docker image (see Installation above), Claude Desktop will automatically launch the container when needed. Simply add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "grouper": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GROUPER_BASE_URL=https://your-grouper-instance.edu/grouper-ws/servicesRest/json/v4_0_000",
        "-e", "GROUPER_USERNAME=your_username",
        "-e", "GROUPER_PASSWORD=your_password",
        "grouper-mcp:latest"
      ]
    }
  }
}

For detailed setup instructions including configuration file locations, local installation, troubleshooting, and more, see Claude Desktop Setup Guide.

With Open WebUI

Open WebUI (v0.6.31+) supports MCP servers via HTTP/SSE using MCPO as a proxy.

Quick Start:

1. Build and run the HTTP-enabled Docker image as a persistent service:

   docker build -f Dockerfile.http -t grouper-mcp:http .
   # Start the HTTP server (runs continuously - Open WebUI connects to this endpoint)
   docker run -p 8000:8000 \
     -e GROUPER_BASE_URL="https://your-grouper-instance.edu/grouper-ws/servicesRest/json/v4_0_000" \
     -e GROUPER_USERNAME="your_username" \
     -e GROUPER_PASSWORD="your_password" \
     -e MCPO_API_KEY="your-secret-key" \
     grouper-mcp:http

2. In Open WebUI:

   • Navigate to ⚙️ Admin Settings → External Tools
   • Click + (Add Server)
   • Select MCP (Streamable HTTP)
   • Server URL: http://localhost:8000
   • API Key: your-secret-key

3. Start chatting and Grouper tools will be available automatically!

For complete setup instructions, MCPO installation options, production deployment, and troubleshooting, see Open WebUI Setup Guide.

HTTP/SSE Access with MCPO

MCPO (MCP-to-OpenAPI Proxy) converts the MCP server to HTTP/SSE, enabling RESTful API access with auto-generated documentation.

Quick Start:

# Build and run the all-in-one HTTP image as a persistent service
docker build -f Dockerfile.http -t grouper-mcp:http .
# Start the HTTP server (runs continuously - clients connect to this endpoint)
docker run -p 8000:8000 \
  -e GROUPER_BASE_URL="https://your-grouper-instance.edu/grouper-ws/servicesRest/json/v4_0_000" \
  -e GROUPER_USERNAME="your_username" \
  -e GROUPER_PASSWORD="your_password" \
  -e MCPO_API_KEY="your-secret-key" \
  grouper-mcp:http

# Access the API (once the server is running)
# - Interactive docs: http://localhost:8000/docs
# - OpenAPI schema: http://localhost:8000/openapi.json

Example API Call:

curl -X POST http://localhost:8000/grouper_find_groups_by_name_approximate \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"searchTerm": "engineering"}'

For complete HTTP setup including separate MCPO installation, production deployment with reverse proxy, advanced configuration, and troubleshooting, see HTTP/MCPO Setup Guide.

Examples

Create a new group

Create a group named "edu:department:engineering:students" with display name "Engineering Students"

Add members to a group

Add user "jdoe" to the group "edu:department:engineering:students"

Search for groups

Find all groups containing "engineering" in their name

Get group by UUID

Get details for group with UUID "12345678-1234-1234-1234-123456789abc"

Create a composite group

Create a composite UNION group named "edu:department:all-staff" using left group "edu:department:faculty" and right group "edu:department:staff"

Assign attributes

Assign attribute "classification" with value "academic" to group "edu:department:engineering:students"

Get subject details

Get detailed information for subject with ID "jdoe123"

Search subjects

Search for subjects containing "Smith" in their name or other searchable fields

Logging

The server automatically logs all activity to ~/.grouper-mcp/logs/:

• grouper-mcp.log - All messages (info, debug, errors)
• grouper-mcp-errors.log - Error messages only

Set GROUPER_DEBUG=true to enable verbose debug logging for troubleshooting.

For complete logging configuration including custom log directories and Docker log access, see Configuration Guide.

Testing

A comprehensive regression test suite is included for validating the MCP server against a Grouper instance:

# Build and run all tests
npm run build
npx tsx tests/run-tests.ts

# Run specific test or category
npx tsx tests/run-tests.ts --test group-2.1
npx tsx tests/run-tests.ts --category members --verbose

The test suite covers 60 tests across all tool categories including groups, stems, members, privileges, composite groups, and more.

For complete testing documentation including environment setup, test configuration, and CI/CD integration, see Testing Guide.

Use Cases

Real-world use cases and examples are documented in the use-cases/ directory, including:

• AI-Assisted Cohort Definition - Using AI to help users build complex cohorts with set theory on basis groups

These use cases drive feature development and demonstrate practical applications of the MCP server.

Planned Features

Planned features and improvements are tracked in TODO.md.

API Compatibility

This server is designed to work with Grouper v4.0.000 web services API. It should be compatible with most recent versions of Grouper.

Feedback & Questions

We welcome all kinds of feedback, including:

• Feature requests and ideas
• Bug reports
• Use case questions
• General feedback and suggestions
• Contributions and improvements

Please send your feedback to [email protected]