Teleport
The easiest, and most secure way to access and protect all of your infrastructure.
Installation
npx mcp-teleportAsk AI about Teleport
Powered by Claude Β· Grounded in docs
I know everything about Teleport. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP Teleport
A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Teleport infrastructure through the tsh CLI.
Overview
MCP Teleport bridges the gap between AI assistants and Teleport infrastructure by providing a standardized interface for:
- Authentication: Login and session management
- SSH Access: Secure shell access to remote nodes
- Kubernetes: Cluster discovery & authentication
- Application Access: Web application tunneling
Features
π Authentication Tools
teleport_login- Login to Teleport clustersteleport_status- Check current authentication statusteleport_list_clusters- List available clusters
π₯οΈ SSH Tools
teleport_list_ssh_nodes- List available SSH nodesteleport_ssh- Execute commands on remote SSH nodes
βΈοΈ Kubernetes Tools
teleport_kube_list_clusters- List available Kubernetes clustersteleport_kube_login- Login to Kubernetes clusters and update kubeconfig
π Application Tools (Coming Soon)
teleport_apps- List available applicationsteleport_app_login- Access web applications
π οΈ Operational Features
- Multiple Transports: stdio, SSE, streamable HTTP
- Dry Run Mode: Test operations safely
- Debug Logging: Comprehensive troubleshooting
- Command Timeouts: Prevent hanging operations
- Structured Responses: Consistent error handling
Prerequisites
- Go 1.24+ (for building from source)
- Teleport CLI (
tsh) installed and configured - Active Teleport cluster access
Install Teleport CLI
# macOS
brew install teleport
# Linux (Ubuntu/Debian)
curl -O https://get.gravitational.com/teleport-v15.1.0-linux-amd64-bin.tar.gz
tar -xzf teleport-v15.1.0-linux-amd64-bin.tar.gz
sudo mv teleport/tsh /usr/local/bin/
# Verify installation
tsh version
Installation
Download Pre-built Binaries
Download the latest release for your platform from the releases page.
# Linux/macOS
wget https://github.com/giantswarm/mcp-teleport/releases/latest/download/mcp-teleport_Linux_x86_64.tar.gz
tar -xzf mcp-teleport_Linux_x86_64.tar.gz
sudo mv mcp-teleport /usr/local/bin/
# Verify installation
mcp-teleport version
Build from Source
# Clone repository
git clone https://github.com/giantswarm/mcp-teleport.git
cd mcp-teleport
# Build
go build -o mcp-teleport
# Optional: Install to PATH
sudo mv mcp-teleport /usr/local/bin/
Go Install
go install github.com/giantswarm/mcp-teleport@latest
Usage
Standalone Server
Start with Default Settings (stdio)
mcp-teleport
Web-based Deployment (SSE)
mcp-teleport serve --transport=sse --http-addr=:8080
Debug Mode with Dry Run
mcp-teleport serve --debug --dry-run
Integration with Claude Desktop
-
Install mcp-teleport (see installation section above)
-
Configure Claude Desktop:
Open Claude Desktop settings and add to your MCP servers configuration:
{ "mcpServers": { "teleport": { "command": "mcp-teleport", "args": ["serve"] } } }Alternative with full path:
{ "mcpServers": { "teleport": { "command": "/usr/local/bin/mcp-teleport", "args": ["serve", "--debug"] } } } -
Restart Claude Desktop
-
Start Interacting:
- "Check my Teleport login status"
- "List all SSH nodes available through Teleport"
- "SSH to server web-01 and run 'uptime'"
- "Login to Teleport cluster teleport.example.com as user alice"
- "List all Kubernetes clusters I can access"
- "Login to the production Kubernetes cluster"
Command Reference
# Server commands
mcp-teleport # Start with stdio transport
mcp-teleport serve --transport=sse # Start with SSE transport
mcp-teleport serve --debug # Enable debug logging
mcp-teleport serve --dry-run # Simulate operations
# Utility commands
mcp-teleport version # Show version
mcp-teleport selfupdate # Update to latest version
mcp-teleport --help # Show help
Configuration
Server Options
| Flag | Description | Default |
|---|---|---|
--transport | Transport type: stdio, sse, streamable-http | stdio |
--http-addr | HTTP server address | :8080 |
--debug | Enable debug logging | false |
--dry-run | Simulate operations | false |
--non-destructive | Prevent destructive operations | true |
Transport Types
STDIO (Default)
Perfect for Claude Desktop integration:
mcp-teleport serve
Server-Sent Events (SSE)
For web applications requiring real-time updates:
mcp-teleport serve --transport=sse --http-addr=:8080
Access at: http://localhost:8080/sse
Streamable HTTP
For modern web applications:
mcp-teleport serve --transport=streamable-http --http-addr=:8080
Access at: http://localhost:8080/mcp
Example Interactions
Authentication
User: "Check my current Teleport login status"
AI: Uses teleport_status tool
Response: Current login information and certificate details
User: "Login to teleport.example.com as user alice"
AI: Uses teleport_login tool with proxy and user parameters
Response: Login success confirmation
SSH Operations
User: "List all SSH servers I can access"
AI: Uses teleport_list_ssh_nodes tool
Response: Available SSH nodes with details
User: "SSH to web-server-01 and check disk usage"
AI: Uses teleport_ssh tool with destination and command
Response: Command output from remote server
Kubernetes Operations
User: "List all Kubernetes clusters I can access"
AI: Uses teleport_kube_list_clusters tool
Response: Available K8s clusters with labels and metadata
User: "Login to the production Kubernetes cluster"
AI: Uses teleport_kube_login tool with kubeCluster parameter
Response: Kubeconfig updated, kubectl access configured
User: "Show me all clusters with environment=production label"
AI: Uses teleport_kube_list_clusters with query parameter
Response: Filtered list of production clusters
Development
Project Structure
mcp-teleport/
βββ cmd/ # CLI commands and entry points
β βββ root.go # Root command setup
β βββ serve.go # Server command with transport options
β βββ version.go # Version command
β βββ selfupdate.go # Self-update functionality
βββ internal/
β βββ server/ # Server context and configuration
β β βββ context.go # Server context management
β β βββ doc.go # Package documentation
β βββ teleport/ # Teleport CLI wrapper
β β βββ client.go # tsh command execution
β β βββ client_test.go # Unit tests
β β βββ doc.go # Package documentation
β βββ tools/ # MCP tool implementations
β βββ auth/ # Authentication tools
β βββ ssh/ # SSH tools
β βββ kube/ # Kubernetes tools
β βββ database/ # Database tools (stubs)
β βββ apps/ # Application tools (stubs)
βββ .goreleaser.yaml # Release configuration
βββ go.mod # Go module definition
βββ LICENSE # MIT license
βββ Makefile # Build automation
βββ README.md # This file
Building
# Install dependencies
go mod download
# Run tests
go test -v ./...
# Build binary
go build -o mcp-teleport
# Build for all platforms
goreleaser build --snapshot --clean
Testing
# Run all tests
make test
# Run tests with coverage
go test -cover ./...
# Test server in dry-run mode
./mcp-teleport serve --dry-run --debug
Adding New Tools
- Create tool package in
internal/tools/ - Implement tool registration function
- Add handler functions for each tool
- Register in serve.go
- Add tests for new functionality
Example:
// internal/tools/example/tools.go
func RegisterExampleTools(s *mcpserver.MCPServer, sc *server.ServerContext) error {
tool := mcp.NewTool("teleport_example", ...)
s.AddTool(tool, handleExample)
return nil
}
Security Considerations
- Principle of Least Privilege: Run with minimal required permissions
- Network Security: Use HTTPS for web transports in production
- Teleport RBAC: Ensure proper Teleport role-based access controls
- Command Validation: All tsh commands are validated before execution
- Timeout Protection: Commands timeout after 30 seconds to prevent hanging
Production Deployment
# Use non-destructive mode in production
mcp-teleport serve --non-destructive
# Enable logging for audit trail
mcp-teleport serve --debug
# Consider running as dedicated user
sudo -u teleport-mcp mcp-teleport serve
Troubleshooting
Common Issues
β "tsh command not found"
# Verify tsh installation
which tsh
tsh version
# Add to PATH if needed
export PATH=$PATH:/usr/local/bin
β "Command timeout after 30 seconds"
- Check network connectivity to Teleport cluster
- Verify proxy address is correct
- Try with
--debugflag for detailed logging
β "Permission denied"
- Ensure valid Teleport login session
- Check Teleport user permissions
- Verify RBAC policies allow requested operations
β "Failed to start MCP server"
- Check if port is already in use (for web transports)
- Verify Go binary has execute permissions
- Try with
--debugflag for detailed error information
Debug Mode
Enable comprehensive logging:
mcp-teleport serve --debug --dry-run
Logs Analysis
# Check recent logs (if using systemd)
journalctl -u mcp-teleport -f
# View server output
mcp-teleport serve --debug 2>&1 | tee mcp-teleport.log
Contributing
We welcome contributions! Please see our Contributing Guidelines for details.
Quick Start for Contributors
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Test your changes:
make test - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
Development Setup
# Clone your fork
git clone https://github.com/yourusername/mcp-teleport.git
cd mcp-teleport
# Install dependencies
go mod download
# Run tests
make test
# Build and test locally
make build
./mcp-teleport serve --dry-run --debug
Roadmap
- v1.1: Complete Kubernetes tools implementation β
- v1.2: Database tools implementation
- v1.3: Application tools implementation
- v1.4: Resource management tools
- v2.0: Advanced workflow automation
- v2.1: Teleport Connect integration
- v2.2: Multi-cluster management
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Teleport - Modern infrastructure access platform
- Model Context Protocol - Standardized AI integration
- mcp-kubernetes - Structural inspiration
- Claude - AI assistant integration target
Support
- Documentation: GitHub Wiki
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: support@giantswarm.io
Made with β€οΈ by Giant Swarm
SSH Command Execution
The teleport_ssh tool supports two destination formats:
1. Direct Hostname Targeting
# Target a specific node
"destination": "root@hostname"
2. Label Selector Targeting (Multi-Node)
# Target all nodes matching label criteria
"destination": "root@role=worker,env=prod"
"destination": "root@cluster=wallaby,role=control-plane"
Important: Only one-time commands are supported. Interactive shell sessions are not supported via MCP.
Expected Output Formats
Single Node Output:
total 408
drwxr-xr-x. 8 root root 4096 Mar 26 12:18 kubernetes
drwxr-xr-x. 1 root root 4096 Mar 26 12:18 sysctl.d
Multi-Node Output (Label Selector):
WARNING: Multiple nodes matched label selector, running command on all.
Running command on wallaby-9wldd:
Running command on wallaby-rd565:
[wallaby-9wldd] 07:15:15 up 92 days, 18:59, 0 user, load average: 1.71, 1.55, 1.47
[wallaby-rd565] 07:15:15 up 92 days, 19:05, 0 user, load average: 1.10, 0.92, 0.90
[wallaby-9wldd] success
[wallaby-rd565] success
2 host(s) succeeded; 0 host(s) failed
SSH Node Listing
The teleport_list_ssh_nodes tool returns JSON formatted node information:
[
{
"kind": "node",
"version": "v2",
"metadata": {
"name": "41c3ee63-af98-44b1-9ec6-14cb19ba7e6b",
"labels": {
"azure/environment": "prod",
"cluster": "wallaby",
"role": "control-plane"
}
},
"spec": {
"hostname": "wallaby-9wldd",
"addr": "",
"cmd_labels": {
"arch": {"result": "x86_64"},
"role": {"result": "control-plane"}
}
}
}
]
This is parsed and presented in a user-friendly format showing hostname, labels, and dynamic command labels.
Kubernetes Cluster Management
Kubernetes Cluster Discovery
The teleport_kube_list_clusters tool provides comprehensive cluster discovery with filtering capabilities:
Basic Usage
# List all accessible clusters
"No additional parameters needed"
Advanced Filtering
# Search by name or description
"search": "production,staging"
# Filter by labels
"labels": "env=prod,region=us-east"
# Query with predicate language
"query": "labels[\"environment\"] == \"production\""
# Show detailed information
"verbose": true
# List from all Teleport clusters
"all": true
Expected Output Format
Found 2 Kubernetes cluster(s):
β’ prod-east-k8s (selected)
Labels: 2 available (use verbose=true to see details)
β’ staging-west-k8s
Labels: env=staging, region=us-west-1
Tip: Use verbose=true to see detailed label information for each cluster.
Kubernetes Cluster Authentication
The teleport_kube_login tool handles cluster authentication and kubeconfig management:
Single Cluster Login
# Login to specific cluster
"kubeCluster": "prod-east-k8s"
# Login with custom context name
"kubeCluster": "prod-east-k8s",
"contextName": "my-prod-context"
# Login with user/group impersonation
"kubeCluster": "prod-east-k8s",
"asUser": "admin",
"asGroups": "system:masters"
# Login with default namespace
"kubeCluster": "prod-east-k8s",
"kubeNamespace": "production"
Batch Login (All Clusters)
# Login to all accessible clusters
"all": true
# Login to filtered clusters
"all": true,
"labels": "env=prod"
# Login with custom context template
"all": true,
"contextName": "teleport-{{.KubeName}}"
Expected Behavior
- Updates your local kubeconfig automatically
- Provides clear success/failure feedback
- Handles MFA challenges gracefully
- Supports both single and batch operations
- Only uses
tsh kube login- no manual kubeconfig manipulation
Important: Either kubeCluster or all=true must be specified, but not both.
