Adolfo Delorenzo
be1e05c382
Major configuration and tooling updates: Authentication Changes: - Remove username/password authentication support - Require PORTAINER_URL and PORTAINER_API_KEY (both mandatory) - Simplify PortainerConfig class and validation logic - Update all documentation to reflect API key requirement Multiple Runtime Support: - Add uvx support for running without installation - Add uv support with dedicated wrapper script - Add npx support with Node.js wrapper script - Maintain backward compatibility with direct Python execution Documentation Updates: - Comprehensive README.md with all execution methods - Detailed USAGE.md with step-by-step instructions - Updated .env.example with clear required vs optional sections - Enhanced docstrings in server.py and config.py Tooling Support: - package.json for npm/npx support with cross-platform wrapper - scripts/run-with-uv.py for uv integration - bin/portainer-core-mcp Node.js wrapper for npx - test_uvx.py for uvx functionality testing Configuration Improvements: - Clear separation of required vs optional environment variables - Better validation error messages - Simplified authentication flow - Enhanced project metadata in pyproject.toml 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
276 lines
5.1 KiB
Markdown
276 lines
5.1 KiB
Markdown
# Portainer Core MCP Server Usage Guide
|
|
|
|
## Quick Start
|
|
|
|
### 1. Set Required Environment Variables
|
|
|
|
```bash
|
|
# Required configuration
|
|
export PORTAINER_URL=https://your-portainer-instance.com
|
|
export PORTAINER_API_KEY=your-api-key-here
|
|
```
|
|
|
|
### 2. Generate Portainer API Key
|
|
|
|
1. Log in to your Portainer instance
|
|
2. Navigate to **User Settings** > **API Tokens**
|
|
3. Click **Add API Token**
|
|
4. Give it a name (e.g., "MCP Server")
|
|
5. Copy the generated token
|
|
|
|
### 3. Start the Server
|
|
|
|
Choose your preferred method:
|
|
|
|
#### Option A: Using Python (Direct)
|
|
```bash
|
|
python run_server.py
|
|
```
|
|
|
|
#### Option B: Using uv (Recommended)
|
|
```bash
|
|
# Install uv if not installed
|
|
pip install uv
|
|
|
|
# Run with uv
|
|
uv run python run_server.py
|
|
```
|
|
|
|
#### Option C: Using uvx (Run without installing)
|
|
```bash
|
|
# Install uv if not installed
|
|
pip install uv
|
|
|
|
# Run directly without installation
|
|
uvx --from . portainer-core-mcp
|
|
```
|
|
|
|
#### Option D: Using npm/npx
|
|
```bash
|
|
# Install globally
|
|
npm install -g portainer-core-mcp
|
|
|
|
# Run with npx
|
|
npx portainer-core-mcp
|
|
```
|
|
|
|
#### Option E: Using the uv wrapper script
|
|
```bash
|
|
# Make executable (if not already)
|
|
chmod +x scripts/run-with-uv.py
|
|
|
|
# Run with uv wrapper
|
|
python scripts/run-with-uv.py
|
|
```
|
|
|
|
## Environment Configuration
|
|
|
|
### Using .env File
|
|
|
|
1. Copy the example file:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
2. Edit the file:
|
|
```bash
|
|
nano .env
|
|
```
|
|
|
|
3. Set your values:
|
|
```bash
|
|
# Required
|
|
PORTAINER_URL=https://your-portainer-instance.com
|
|
PORTAINER_API_KEY=your-api-key-here
|
|
|
|
# Optional (with defaults)
|
|
HTTP_TIMEOUT=30
|
|
MAX_RETRIES=3
|
|
LOG_LEVEL=INFO
|
|
DEBUG=false
|
|
```
|
|
|
|
### Using Environment Variables
|
|
|
|
```bash
|
|
# Export variables
|
|
export PORTAINER_URL=https://your-portainer-instance.com
|
|
export PORTAINER_API_KEY=your-api-key-here
|
|
|
|
# Start server
|
|
python run_server.py
|
|
```
|
|
|
|
## Installation Methods
|
|
|
|
### Development Installation
|
|
|
|
```bash
|
|
# Clone and install in development mode
|
|
git clone <repository-url>
|
|
cd portainer-mcp
|
|
pip install -e .
|
|
|
|
# Or with uv
|
|
uv pip install -e .
|
|
```
|
|
|
|
### Production Installation
|
|
|
|
```bash
|
|
# Install from PyPI (when published)
|
|
pip install portainer-core-mcp
|
|
|
|
# Or with uv
|
|
uv pip install portainer-core-mcp
|
|
```
|
|
|
|
### Run Without Installing (uvx)
|
|
|
|
```bash
|
|
# Run directly from source without installation
|
|
uvx --from . portainer-core-mcp
|
|
|
|
# Or from PyPI (when published)
|
|
uvx portainer-core-mcp
|
|
```
|
|
|
|
### NPM Installation
|
|
|
|
```bash
|
|
# Install globally
|
|
npm install -g portainer-core-mcp
|
|
|
|
# Or run without installing
|
|
npx portainer-core-mcp
|
|
```
|
|
|
|
## Available Commands
|
|
|
|
### MCP Tools
|
|
|
|
Once the server is running, the following tools are available:
|
|
|
|
- **`authenticate`** - Login with username/password
|
|
- **`generate_token`** - Generate API tokens
|
|
- **`get_current_user`** - Get current user info
|
|
- **`list_users`** - List all users
|
|
- **`create_user`** - Create new user
|
|
- **`update_user`** - Update user details
|
|
- **`delete_user`** - Delete user
|
|
- **`get_settings`** - Get Portainer settings
|
|
- **`update_settings`** - Update configuration
|
|
- **`health_check`** - Server health status
|
|
|
|
### MCP Resources
|
|
|
|
- **`portainer://users`** - User management data
|
|
- **`portainer://settings`** - Configuration settings
|
|
- **`portainer://health`** - Server health status
|
|
|
|
## Testing
|
|
|
|
### Run Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
python -m pytest
|
|
|
|
# Run with coverage
|
|
python -m pytest --cov=src
|
|
|
|
# Run specific test file
|
|
python -m pytest tests/test_basic.py
|
|
```
|
|
|
|
### Test Configuration
|
|
|
|
```bash
|
|
# Test configuration loading
|
|
python -c "
|
|
import os
|
|
os.environ['PORTAINER_URL'] = 'https://test.com'
|
|
os.environ['PORTAINER_API_KEY'] = 'test-key'
|
|
from src.portainer_core.config import get_config
|
|
config = get_config()
|
|
print('✅ Configuration OK')
|
|
print(f'URL: {config.portainer_url}')
|
|
print(f'API Base: {config.api_base_url}')
|
|
"
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Missing API Key Error**
|
|
```
|
|
ValueError: PORTAINER_API_KEY must be provided and cannot be empty
|
|
```
|
|
**Solution**: Set the `PORTAINER_API_KEY` environment variable
|
|
|
|
2. **Invalid URL Error**
|
|
```
|
|
ValueError: Invalid Portainer URL
|
|
```
|
|
**Solution**: Ensure `PORTAINER_URL` includes the protocol (http/https)
|
|
|
|
3. **Python Not Found (npx)**
|
|
```
|
|
Error: Python is not installed or not in PATH
|
|
```
|
|
**Solution**: Install Python 3.8+ and ensure it's in your PATH
|
|
|
|
### Debug Mode
|
|
|
|
Enable debug logging for troubleshooting:
|
|
|
|
```bash
|
|
DEBUG=true LOG_LEVEL=DEBUG python run_server.py
|
|
```
|
|
|
|
### Health Check
|
|
|
|
Test if the server is working:
|
|
|
|
```bash
|
|
# Check server health
|
|
curl -X POST http://localhost:8000/health
|
|
|
|
# Or use the health_check tool through MCP
|
|
```
|
|
|
|
## Advanced Usage
|
|
|
|
### Custom Configuration
|
|
|
|
```python
|
|
from portainer_core.config import PortainerConfig
|
|
|
|
# Create custom config
|
|
config = PortainerConfig(
|
|
portainer_url="https://custom.portainer.com",
|
|
portainer_api_key="custom-key",
|
|
http_timeout=60,
|
|
log_level="DEBUG"
|
|
)
|
|
```
|
|
|
|
### Programmatic Usage
|
|
|
|
```python
|
|
from portainer_core.server import create_server
|
|
import asyncio
|
|
|
|
async def main():
|
|
server = create_server()
|
|
await server.run()
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
## Support
|
|
|
|
- **Documentation**: See README.md and code comments
|
|
- **Issues**: Report via GitHub Issues
|
|
- **Configuration**: Check .env.example for all options |