⚠️ DISCLAIMER: This is an unofficial, community-developed tool and is NOT an official Cato Networks release. It is not affiliated with, endorsed by, or supported by Cato Networks. Use at your own risk.
A Model Context Protocol (MCP) server that provides SCIM (System for Cross-domain Identity Management) tools for managing users and groups in Cato Networks. This allows LLMs to interact with Cato Networks' identity management system through a standardized protocol.
- Full SCIM User Management: Create, read, update, and delete users
- Full SCIM Group Management: Create, read, update, and delete groups
- MCP Protocol Support: Expose SCIM operations as MCP tools for LLM consumption
- Docker Support: Run as a containerized service for easy deployment
- Auto-generation: Automatic generation of external IDs and passwords
- CLI Tools: Command-line interfaces for direct user and group creation
- Comprehensive Testing: Unit tests and integration examples
- Clone the repository:
git clone https://github.com/yourusername/scimcp.git
cd scimcp- Install dependencies:
# Basic dependencies
pip install -r requirements.txt
# Development dependencies (includes pytest)
pip install -r requirements-dev.txt- Configure environment:
cp .env.example .env
# Edit .env with your Cato Networks SCIM credentialsFor production deployment, use Docker:
# Build the image
docker build -t scimcp:latest .
# Or use docker-compose
docker-compose up -dThe application uses environment variables for configuration. Create a .env file:
# Required: Cato Networks SCIM API credentials
SCIM_BASE_URL=https://api.catonetworks.com/api/v1/scim/v2.0
SCIM_TOKEN=your-bearer-token-here
# Optional: Enable debug logging
DEBUG=falseThe SCIMClient class provides a simple interface for SCIM operations:
from scimcp import SCIMClient
# Initialize client (reads from environment or .env file)
client = SCIMClient()
# Create a user (auto-generates externalId and password)
response = client.create_user(
email="john.doe@example.com",
firstName="John",
lastName="Doe"
)
# Create a group (auto-generates 8-digit externalId)
response = client.create_group(displayName="Engineering Team")
# List users with filtering
response = client.get_users(filter_expr='userName sw "john"')
# Get specific user
response = client.get_user(user_id="12345")
# Update a group (e.g., rename) - MUST include externalId
group_response = client.get_group(group_id="67890")
group_data = group_response.json()
group_data["displayName"] = "New Engineering Team Name"
# IMPORTANT: Keep the externalId when updating
update_response = client.update_group(group_id="67890", group_data=group_data)
# Add users to a group
response = client.add_members_to_group(
group_id="67890",
user_ids=["user123", "user456", "user789"]
)
# Remove users from a group
response = client.remove_members_from_group(
group_id="67890",
user_ids=["user456"]
)Command-line tools for quick operations:
# Create a user
python examples/create_user_cli.py \
--email john.doe@example.com \
--firstName John \
--lastName Doe
# Create a group
python examples/create_group_cli.py \
--displayName "Engineering Team"
# With custom external ID
python examples/create_group_cli.py \
--displayName "Sales Team" \
--externalId SALES001
# Dry run to preview
python examples/create_user_cli.py \
--email test@example.com \
--firstName Test \
--lastName User \
--dry-runThe MCP server exposes SCIM operations as tools:
# Run directly
python -m scimcp.mcp_server
# Or with Docker
docker run -e SCIM_BASE_URL=$SCIM_BASE_URL -e SCIM_TOKEN=$SCIM_TOKEN scimcp:latestBuild the Docker image locally:
# Standard build
docker build -t scimcp:latest .
# Multi-platform build (for ARM and x86)
docker buildx build --platform linux/amd64,linux/arm64 -t scimcp:latest .
# With specific version tag
docker build -t scimcp:1.0.0 .The easiest way to run the MCP server:
# Start the service
docker-compose up -d
# View logs
docker-compose logs -f scimcp
# Stop the service
docker-compose down
# Rebuild after code changes
docker-compose up -d --buildRun the container directly:
# Basic run
docker run -d \
--name scimcp-server \
-e SCIM_BASE_URL="https://api.catonetworks.com/api/v1/scim/v2.0" \
-e SCIM_TOKEN="your-token-here" \
scimcp:latest
# With resource limits
docker run -d \
--name scimcp-server \
-e SCIM_BASE_URL="$SCIM_BASE_URL" \
-e SCIM_TOKEN="$SCIM_TOKEN" \
--memory="256m" \
--cpus="0.5" \
scimcp:latest
# Interactive mode for debugging
docker run -it --rm \
-e SCIM_BASE_URL="$SCIM_BASE_URL" \
-e SCIM_TOKEN="$SCIM_TOKEN" \
-e DEBUG=true \
scimcp:latestThe MCP server provides the following tools:
scim_list_users- List or search users with optional filteringscim_get_user- Get a specific user by IDscim_create_user- Create a new userscim_update_user- Update an existing user (preserve externalId when updating)scim_delete_user- Delete a user
scim_list_groups- List or search groups with optional filteringscim_get_group- Get a specific group by IDscim_create_group- Create a new groupscim_update_group- Update an existing group (IMPORTANT: Must include existing externalId when renaming)scim_delete_group- Delete a groupscim_add_users_to_group- Add users to a group using PATCH operationscim_remove_users_from_group- Remove users from a group using PATCH operation
When updating users or groups, especially when renaming:
- Always include the existing
externalIdin the update payload to preserve it - The update operation replaces the entire resource, so include all fields you want to keep
- For group renaming: First fetch the group, then update with both new
displayNameand existingexternalId
To use this MCP server with an LLM client, add it to your MCP configuration:
{
"mcpServers": {
"scimcp": {
"command": "docker",
"args": ["run", "-i", "--rm",
"-e", "SCIM_BASE_URL=https://api.catonetworks.com/api/v1/scim/v2.0",
"-e", "SCIM_TOKEN=your-token-here",
"scimcp:latest"]
}
}
}Or for local development:
{
"mcpServers": {
"scimcp": {
"command": "python",
"args": ["-m", "scimcp.mcp_server"],
"env": {
"SCIM_BASE_URL": "https://api.catonetworks.com/api/v1/scim/v2.0",
"SCIM_TOKEN": "your-token-here"
}
}
}
}get_users(filter_expr=None, start_index=1, count=100)- List usersget_user(user_id)- Get specific usercreate_user(email, firstName, lastName, externalId=None, password=None)- Create userupdate_user(user_id, user_data)- Update userdelete_user(user_id)- Delete user
get_groups(filter_expr=None, start_index=1, count=100)- List groupsget_group(group_id)- Get specific groupcreate_group(displayName, externalId=None)- Create groupupdate_group(group_id, group_data)- Update groupdelete_group(group_id)- Delete groupadd_members_to_group(group_id, user_ids)- Add users to groupremove_members_from_group(group_id, user_ids)- Remove users from grouppatch_group(group_id, patch_operations)- Apply PATCH operations to group
- User External ID: 12-character alphanumeric string
- User Password: Easy-to-remember format (Word-Word-Digits)
- Group External ID: 8-digit number
Run the test suite:
# All tests
python -m pytest
# Unit tests only
python -m pytest tests/
# With coverage
python -m pytest --cov=scimcp tests/
# Integration tests (requires valid credentials)
python examples/integration_test.py
# Basic usage examples
python examples/basic_usage.pyscimcp/
├── scimcp/ # Main package
│ ├── __init__.py
│ ├── scim_client.py # SCIM client implementation
│ └── mcp_server.py # MCP server implementation
├── tests/ # Unit tests
│ ├── __init__.py
│ ├── conftest.py # Test fixtures
│ └── test_scim_client.py # Client tests
├── examples/ # Usage examples
│ ├── integration_test.py # Integration tests
│ ├── basic_usage.py # Usage examples
│ ├── create_user_cli.py # User creation CLI
│ └── create_group_cli.py # Group creation CLI
├── .env.example # Environment template
├── .gitignore # Git ignore rules
├── Dockerfile # Docker image definition
├── docker-compose.yml # Docker Compose configuration
├── LICENSE # Apache 2.0 license
├── README.md # This file
├── requirements.txt # Python dependencies
└── requirements-dev.txt # Development dependencies
-
Authentication Errors
- Verify your SCIM token is valid
- Check the SCIM_BASE_URL is correct
- Ensure the token has necessary permissions
-
Docker Build Failures
- Ensure Docker is installed and running
- Check available disk space
- Try building with
--no-cacheflag
-
MCP Connection Issues
- Verify the container is running:
docker ps - Check logs:
docker logs scimcp-server - Ensure environment variables are set correctly
- Verify the container is running:
Enable debug logging to see detailed request/response information:
# Environment variable
export DEBUG=true
# Or in .env file
DEBUG=true
# Or when running Docker
docker run -e DEBUG=true ...Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
For issues, questions, or contributions, please:
- Open an issue on GitHub
- Check existing documentation
- Review the examples directory
- Cato Networks for providing the SCIM API
- MCP protocol by Anthropic for standardized LLM tool integration