portainer-mcp/CLAUDE.md

Portainer Core MCP Server

This MCP server provides authentication and core management functionality for Portainer Business Edition.

Server Purpose

Primary Functions:

• User authentication and session management
• API token generation and validation
• User profile and settings management
• Basic system information retrieval

Part of Portainer MCP Suite:

• portainer-core - Authentication and user management (this server)
• portainer-teams - Teams and RBAC management
• portainer-environments - Environment and endpoint management
• portainer-docker - Docker container operations
• portainer-kubernetes - Kubernetes cluster management
• portainer-stacks - Stack deployment and management
• portainer-edge - Edge computing and device management

Authentication Flow

Required for all operations:

1. Initialize admin user (first time setup)
2. Authenticate to get JWT token
3. Use token in X-API-Key header for all requests

Token Management:

• Tokens expire based on server configuration
• Generate new tokens before expiration
• Store tokens securely in environment variables

Base Configuration

Environment Variables:

PORTAINER_URL=https://your-portainer-instance.com
PORTAINER_API_KEY=your-api-token

API Base URLs:

• Business Edition: {PORTAINER_URL}/api
• All endpoints require authentication except initial admin setup

Common Response Patterns

Success Response Structure:

{
  "Id": 1,
  "Username": "admin",
  "Role": 1,
  "CreationDate": 1631852794
}

Error Response Structure:

{
  "message": "Invalid credentials",
  "details": "Authentication failed"
}

Core Endpoint Categories

Authentication Endpoints:

• POST /api/users/admin/init - Initialize admin user
• POST /api/auth - Authenticate user
• POST /api/users/{id}/tokens - Generate API token
• DELETE /api/auth - Logout/invalidate session

User Management:

• GET /api/users - List users
• POST /api/users - Create user
• GET /api/users/{id} - Get user details
• PUT /api/users/{id} - Update user
• DELETE /api/users/{id} - Delete user

Settings:

• GET /api/settings - Get Portainer settings
• PUT /api/settings - Update settings
• GET /api/settings/public - Get public settings

Error Handling

Common HTTP Status Codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (invalid/missing token)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found
• 409 - Conflict (resource already exists)
• 500 - Internal Server Error

Retry Logic:

• Implement exponential backoff for 5xx errors
• Refresh token on 401 responses
• Maximum 3 retry attempts

Security Considerations

Best Practices:

• Always use HTTPS in production
• Rotate API tokens regularly
• Implement proper token storage
• Log authentication events
• Rate limit API calls

RBAC Integration:

• Check user permissions before operations
• Respect environment-level access controls
• Honor team-based restrictions

Development Workflow

Testing Authentication:

# Test admin initialization
curl -X POST "${PORTAINER_URL}/api/users/admin/init" \
  -H "Content-Type: application/json" \
  -d '{"Username":"admin","Password":"yourpassword"}'

# Test login
curl -X POST "${PORTAINER_URL}/api/auth" \
  -H "Content-Type: application/json" \
  -d '{"Username":"admin","Password":"yourpassword"}'

Local Development:

• Use Docker Compose with Portainer for testing
• Mock authentication for unit tests
• Validate all endpoints with proper error handling

Integration Notes

With Other MCP Servers:

• Share authentication state across Portainer MCP servers
• Use consistent error handling patterns
• Maintain session context for user operations

Rate Limits:

• Portainer has built-in rate limiting
• Implement client-side throttling
• Monitor for 429 responses

Troubleshooting

Common Issues:

• 401 Unauthorized: Check token validity and format
• 403 Forbidden: Verify user permissions and RBAC settings
• Connection Refused: Confirm Portainer URL and network access
• SSL Errors: Validate certificate configuration

Debug Commands:

# Verify Portainer connectivity
curl -I "${PORTAINER_URL}/api/status"

# Check current user context
curl -H "X-API-Key: ${PORTAINER_API_KEY}" \
  "${PORTAINER_URL}/api/users/me"

Logging:

• Enable verbose logging for authentication flows
• Log all API calls with timestamps
• Mask sensitive data in logs (passwords, tokens)

Version Compatibility

Supported Versions:

• Portainer Business Edition 2.30.x+
• API Version: 2.31.3

Breaking Changes:

• Monitor Portainer release notes for API changes
• Test against new versions before upgrading
• Maintain backward compatibility where possible