Which integrations are available for this server?

Exports Tailscale network metrics and monitoring data to Datadog for centralized observability and alerting. Sends Tailscale network alerts and notifications to Discord channels via webhooks for device connection events and network monitoring. Enables creation and export of Grafana dashboards for Tailscale network monitoring, including comprehensive network overview, device activity tracking, security monitoring, and network topology visualization dashboards. Integrates with PagerDuty for incident management and alerting based on Tailscale network events and security monitoring. Exports custom metrics for Tailscale network monitoring including device activity, network traffic, API performance, and health statistics that can be scraped by Prometheus for monitoring and alerting. Sends Tailscale network alerts and notifications to Slack channels for device connection events and network monitoring. Provides comprehensive management of Tailscale networks including device management (authorization, SSH access, tagging, exit nodes), DNS configuration (MagicDNS, custom records), file sharing via Taildrop, security auditing, monitoring and metrics collection, ACL management, and network topology visualization.

How do I use TailscaleMCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TailscaleMCP list all authorized devices in my network" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

TailscaleMCP

A FastMCP 2.13+ compliant server for managing Tailscale networks with persistent storage, modern Python tooling, and comprehensive CI/CD.

CI/CD Pipeline codecov PyPI version Python 3.10+ FastMCP 2.13+ License: MIT Persistent Storage Ruff

🚀 Features

🔧 Portmanteau Tools: Consolidated tools following the database-mcp pattern to avoid tool explosion
- tailscale_device: Comprehensive device management (list, authorize, rename, tag, SSH, search, stats, exit nodes, subnet routing, user management, auth keys)
- tailscale_network: DNS and network management (MagicDNS, DNS records, resolution, policies, statistics)
- tailscale_monitor: Monitoring and metrics (status, Prometheus metrics, topology, health reports, Grafana dashboards)
- tailscale_file: File sharing via Taildrop (send, receive, transfer management, statistics) - Enhanced with real CLI integration
- tailscale_funnel: Funnel operations for exposing local services to public internet (enable, disable, status, list, certificate info) - NEW
- tailscale_security: Security and compliance (scanning, auditing, threat detection, policy management, alerting)
- tailscale_automation: Workflow automation (workflows, scripts, batch operations, scheduling)
- tailscale_backup: Backup and disaster recovery (backup creation, restoration, scheduling, testing)
- tailscale_performance: Performance monitoring (latency, bandwidth, optimization, capacity planning)
- tailscale_reporting: Advanced reporting (custom reports, analytics, scheduling, export)
- tailscale_integration: Third-party integrations (webhooks, Slack, Discord, PagerDuty, Datadog)
📊 Comprehensive Monitoring Stack: Complete observability with Grafana, Prometheus, and Loki
- Real-time dashboards for network visualization and device monitoring
- Structured logging with JSON format for easy parsing and analysis
- Prometheus metrics for performance monitoring and alerting
- Log aggregation with Loki for centralized log analysis
- Docker Compose setup for easy deployment and management
📈 Grafana Dashboards: 4 comprehensive dashboards for different monitoring needs
- Network Overview: Device status, traffic, API performance
- Logs Dashboard: Error analysis, log streams, security events
- Device Activity: Activity heatmaps, geolocation, timelines
- Comprehensive Monitoring: Combined overview of all metrics and logs
🔍 Network Topology: Visual network topology and device relationships
⚡ Prometheus Metrics: Export metrics for monitoring systems with custom metrics
🏥 Health Reports: Automated health analysis and recommendations
📝 Structured Logging: JSON-formatted logs with rich context for Loki integration
Modern Tooling: FastMCP 2.13+ with persistent storage, Ruff, Pytest, structured logging
💾 Persistent Storage: FastMCP 2.13+ DiskStore backend for funnels, transfers, and preferences (survives Claude Desktop and OS restarts)
- Platform-aware storage locations (Windows: %APPDATA%, macOS: ~/Library/Application Support, Linux: ~/.local/share)
- Encrypted by default with FernetEncryptionWrapper
- See Storage Backends Documentation for details
Container Ready: Docker support with development and production images
CI/CD: Comprehensive GitHub Actions pipeline with security scanning

🎯 Usage

Portmanteau Tools

The TailscaleMCP server uses portmanteau tools following the database-mcp pattern to avoid tool explosion. Each tool combines multiple related operations:

Device Management (`tailscale_device`)

# List all devices
await tailscale_device(operation="list", online_only=True)

# Get device details
await tailscale_device(operation="get", device_id="device123")

# Authorize a device
await tailscale_device(operation="authorize", device_id="device123", authorize=True, reason="New employee")

# Rename device
await tailscale_device(operation="rename", device_id="device123", name="john-laptop")

# Add tags to device
await tailscale_device(operation="tag", device_id="device123", tags=["engineering", "laptop"])

# Enable SSH access
await tailscale_device(operation="ssh", device_id="device123", public_key="ssh-rsa...", key_name="john-key")

# Search devices
await tailscale_device(operation="search", search_query="engineering", search_fields=["name", "tags"])

# Enable exit node
await tailscale_device(operation="exit_node", device_id="device123", enable_exit_node=True, advertise_routes=["0.0.0.0/0"])

Network Management (`tailscale_network`)

# Get DNS configuration
await tailscale_network(operation="dns_config")

# Configure MagicDNS
await tailscale_network(operation="magic_dns", enabled=True, override_local_dns=False)

# Add DNS record
await tailscale_network(operation="dns_record", name="api.internal", record_type="A", value="100.64.0.1")

# Resolve hostname
await tailscale_network(operation="resolve", hostname="api.internal", record_type="A")

# Add search domain
await tailscale_network(operation="search_domain", domain="internal", enabled=True)

# Create network policy
await tailscale_network(operation="policy", policy_name="restrict-api", rules=[{"action": "accept", "src": ["engineering"], "dst": ["api:*"]}])

# Tailscale Services (TailVIPs) — Fall Update
# List services
await tailscale_network(operation="services_list")

# Get a service
await tailscale_network(operation="services_get", service_id="svc-123")

# Create a service
await tailscale_network(
    operation="services_create",
    service_payload={
        "name": "api-service",
        "tailvipIPv4": "100.101.102.103",
        "magicDNS": "api.tail",
        "endpoints": [
            {"deviceId": "device123", "port": 8080, "protocol": "tcp"}
        ],
        "tags": ["prod", "api"]
    }
)

# Update a service
await tailscale_network(
    operation="services_update",
    service_id="svc-123",
    service_payload={"tags": ["prod", "critical"]}
)

# Delete a service
await tailscale_network(operation="services_delete", service_id="svc-123")

Monitoring (`tailscale_monitor`)

# Get network status
await tailscale_monitor(operation="status")

# Get network metrics
await tailscale_monitor(operation="metrics")

# Get Prometheus metrics
await tailscale_monitor(operation="prometheus")

# Generate network topology
await tailscale_monitor(operation="topology")

# Get health report
await tailscale_monitor(operation="health")

# Create Grafana dashboard
await tailscale_monitor(operation="dashboard", grafana_url="http://grafana:3000", api_key="your-api-key")

# Export dashboard
await tailscale_monitor(operation="export", filename="tailscale-dashboard.json", dashboard_type="comprehensive")

File Sharing (`tailscale_file`)

# Send file via Taildrop
await tailscale_file(operation="send", file_path="/path/to/file.txt", recipient_device="device123", sender_device="device456")

# Receive file
await tailscale_file(operation="receive", transfer_id="transfer123", save_path="/downloads/")

# List active transfers
await tailscale_file(operation="list", status_filter="active")

# Cancel transfer
await tailscale_file(operation="cancel", transfer_id="transfer123")

# Get transfer status
await tailscale_file(operation="status", transfer_id="transfer123")

# Get Taildrop statistics
await tailscale_file(operation="stats")

Funnel Operations (`tailscale_funnel`) - NEW

# Enable Funnel for port 8080
await tailscale_funnel(operation="funnel_enable", port=8080)
# Returns public URL: https://your-device.tailnet-name.ts.net:8080

# Disable Funnel for port 8080
await tailscale_funnel(operation="funnel_disable", port=8080)

# Get Funnel status
await tailscale_funnel(operation="funnel_status")

# List all active Funnels
await tailscale_funnel(operation="funnel_list")

# Get certificate information
await tailscale_funnel(operation="funnel_certificate_info", port=8080)

Security Management (`tailscale_security`)

# Security vulnerability scan
await tailscale_security(operation="scan", scan_type="comprehensive")

# Compliance validation
await tailscale_security(operation="compliance", compliance_standard="SOC2")

# Device security audit
await tailscale_security(operation="audit", device_id="device123")

# Generate security report
await tailscale_security(operation="report")

# Monitor suspicious activity
await tailscale_security(operation="monitor")

# Block malicious IP
await tailscale_security(operation="block", ip_address="192.168.1.100", block_duration=3600)

# Quarantine compromised device
await tailscale_security(operation="quarantine", device_id="device123", quarantine_duration=24)

# Create security policy
await tailscale_security(operation="policy", policy_name="restrict-api", rules=[{"action": "accept", "src": ["engineering"], "dst": ["api:*"]}])

Automation (`tailscale_automation`)

# Create automation workflow
await tailscale_automation(operation="workflow_create", workflow_name="daily-backup", workflow_steps=[{"action": "backup", "target": "all"}])

# Execute workflow
await tailscale_automation(operation="workflow_execute", workflow_id="workflow123", execute_now=True)

# Schedule workflow
await tailscale_automation(operation="workflow_schedule", workflow_id="workflow123", schedule_cron="0 2 * * *")

# Execute custom script
await tailscale_automation(operation="script_execute", script_content="print('Hello Tailscale')", script_language="python")

# Batch operations
await tailscale_automation(operation="batch", batch_operations=[{"operation": "authorize", "device_id": "device123"}])

Backup & Recovery (`tailscale_backup`)

# Create configuration backup
await tailscale_backup(operation="backup_create", backup_name="daily-backup", backup_type="full")

# Restore from backup
await tailscale_backup(operation="backup_restore", backup_id="backup123")

# Schedule automated backups
await tailscale_backup(operation="backup_schedule", schedule_cron="0 2 * * *", retention_days=30)

# Test backup integrity
await tailscale_backup(operation="backup_test", backup_id="backup123")

# Create disaster recovery plan
await tailscale_backup(operation="recovery_plan")

Performance Monitoring (`tailscale_performance`)

# Measure network latency
await tailscale_performance(operation="latency", device_id="device123", measure_duration=60)

# Analyze bandwidth utilization
await tailscale_performance(operation="bandwidth", device_id="device123", measure_duration=300)

# Optimize routing performance
await tailscale_performance(operation="optimize", route_optimization=True)

# Establish performance baseline
await tailscale_performance(operation="baseline", baseline_name="production", baseline_duration=300)

# Predict capacity requirements
await tailscale_performance(operation="capacity", capacity_period="30d", scaling_factor=1.2)

# Get scaling recommendations
await tailscale_performance(operation="scaling", scaling_factor=1.5)

Advanced Reporting (`tailscale_reporting`)

# Generate usage analytics report
await tailscale_reporting(operation="usage", date_range="30d", include_charts=True)

# Create custom report
await tailscale_reporting(operation="custom", custom_fields=["device_count", "bandwidth_usage"], date_range="7d")

# Schedule automated reports
await tailscale_reporting(operation="schedule", schedule_cron="0 9 * * 1", email_recipients=["admin@company.com"])

# Export reports
await tailscale_reporting(operation="export", export_path="/reports/", report_format="pdf")

# Deep network analytics
await tailscale_reporting(operation="analytics", analytics_depth="comprehensive", date_range="90d")

# Security metrics
await tailscale_reporting(operation="security", date_range="30d", security_focus=True)

Third-Party Integrations (`tailscale_integration`)

# Create webhook endpoint
await tailscale_integration(operation="webhook_create", webhook_url="https://api.company.com/webhook", webhook_events=["device_connected", "device_disconnected"])

# Test webhook delivery
await tailscale_integration(operation="webhook_test", webhook_id="webhook123")

# Integrate with Slack
await tailscale_integration(operation="slack", slack_channel="#tailscale-alerts", api_key="slack-api-key")

# Integrate with Discord
await tailscale_integration(operation="discord", discord_webhook="https://discord.com/api/webhooks/...")

# Integrate with PagerDuty
await tailscale_integration(operation="pagerduty", pagerduty_key="pagerduty-integration-key")

# Integrate with Datadog
await tailscale_integration(operation="datadog", datadog_api_key="datadog-api-key", api_endpoint="https://api.datadoghq.com")

📦 Installation

From PyPI (Recommended)

pip install tailscalemcp

From Source

git clone https://github.com/yourusername/tailscalemcp.git
cd tailscalemcp
pip install -e .

Using Docker

docker pull tailscalemcp:latest
docker run -p 8000:8000 tailscalemcp:latest

🔧 Quick Start

Basic Usage

import asyncio
from tailscalemcp import TailscaleMCPServer

async def main():
    # Initialize the server
    server = TailscaleMCPServer(
        api_key="your_tailscale_api_key",
        tailnet="your_tailnet"
    )
    
    # Start the server
    await server.start()

if __name__ == "__main__":
    asyncio.run(main())

Using as Context Manager

import asyncio
from tailscalemcp import TailscaleMCPServer

async def main():
    async with TailscaleMCPServer() as server:
        # Server is automatically started
        devices = await server._list_devices_impl()
        print(f"Found {len(devices)} devices")

if __name__ == "__main__":
    asyncio.run(main())

📊 Monitoring Stack

Complete Observability Solution

The TailscaleMCP server includes a comprehensive monitoring stack with Grafana, Prometheus, and Loki for complete observability of your Tailscale network.

Features

📈 Real-time Dashboards: 4 comprehensive Grafana dashboards for different monitoring needs
📝 Structured Logging: JSON-formatted logs with rich context for easy analysis
⚡ Prometheus Metrics: Custom metrics for device activity, network traffic, and API performance
🔍 Log Aggregation: Centralized log collection and analysis with Loki
🐳 Docker Compose: Easy deployment and management of the entire monitoring stack

Quick Start with Monitoring

# Clone and setup
git clone https://github.com/sandraschi/tailscale-mcp.git
cd tailscale-mcp
cp env.example .env

# Edit .env with your Tailscale credentials
# TAILSCALE_API_KEY=your_api_key_here
# TAILSCALE_TAILNET=your_tailnet_name_here

# Start the complete monitoring stack
.\scripts\start-monitoring.ps1

# Access services:
# - Grafana: http://localhost:3000 (admin/admin)
# - Prometheus: http://localhost:9090
# - Loki: http://localhost:3100
# - MCP Server: http://localhost:8080

Available Dashboards

Network Overview: Device status, network traffic, API performance metrics
Logs Dashboard: Error analysis, log streams, security event monitoring
Device Activity: Activity heatmaps, geolocation mapping, device timelines
Comprehensive Monitoring: Combined overview of all metrics and logs

Monitoring Documentation

For detailed information about the monitoring stack, see:

General MCP Monitoring Standards

For comprehensive monitoring standards and reusable templates for all heavyweight MCP servers:

Specialized Monitoring Cases

For specialized monitoring documentation for specific use cases:

Tapo Cameras MCP Monitoring - Home surveillance and security monitoring
Tapo Cameras Dashboard Templates - Specialized Grafana dashboards for home security

Mobile Monitoring Integration

For mobile monitoring solutions:

RebootX Integration - Mobile infrastructure monitoring with RebootX app for iPad
RebootX Integration Guide - Tailscale MCP specific RebootX integration
RebootX On-Prem Setup Guide - Complete setup with fixed IP configuration

⚙️ Configuration

Environment Variables

Variable	Description	Required
`TAILSCALE_API_KEY`	Your Tailscale API key	Yes
`TAILSCALE_TAILNET`	Your Tailnet name	Yes
`LOG_LEVEL`	Logging level (DEBUG, INFO, WARNING, ERROR)	No (default: INFO)
`PROMETHEUS_PORT`	Prometheus metrics port	No (default: 9091)
`LOG_FILE`	Log file path	No (default: logs/tailscale-mcp.log)

Example Configuration

export TAILSCALE_API_KEY="tskey-api-xxxxxxxxxxxxxxxxx"
export TAILSCALE_TAILNET="your-org.tailnet.ts.net"
export LOG_LEVEL="INFO"

Persistent Storage Configuration

TailscaleMCP uses DiskStore for persistent storage by default. Data is automatically stored in platform-appropriate directories:

Windows: %APPDATA%\Tailscale Network Controller MCP\
macOS: ~/Library/Application Support/Tailscale Network Controller MCP/
Linux: ~/.local/share/Tailscale Network Controller MCP/

Storage is encrypted by default and persists across:

✅ Claude Desktop restarts
✅ Operating system reboots
✅ Server restarts

For more information about storage backends and configuration options, see Storage Backends Documentation.

📊 Grafana Dashboard Integration

TailscaleMCP includes comprehensive Grafana dashboard support inspired by the zydepoint/tailscale-dashboard project. You can create beautiful, interactive dashboards for monitoring your Tailscale network.

Dashboard Types

Comprehensive Dashboard: Complete network overview with device status, health scores, bandwidth usage, and historical trends
Network Topology Dashboard: Visual network topology with device relationships and connection maps
Security Dashboard: Security-focused monitoring with ACL overview, access patterns, and security alerts

Creating Dashboards

from tailscalemcp import TailscaleMCPServer

server = TailscaleMCPServer()

# Create comprehensive dashboard
dashboard = await server.create_grafana_dashboard("comprehensive")

# Export dashboard to file
await server.export_grafana_dashboard("comprehensive", "my_dashboard.json")

# Get dashboard summary
summary = await server.get_dashboard_summary("comprehensive")

Monitoring Features

Real-time Metrics: Device counts, health scores, bandwidth usage
Network Topology: Visual representation of device connections
Health Reports: Automated analysis with alerts and recommendations
Prometheus Integration: Export metrics for monitoring systems

Example Dashboard Demo

Run the included demo script to see all dashboard features:

python examples/grafana_dashboard_demo.py

This will create:

Comprehensive monitoring dashboard
Network topology visualization
Security monitoring dashboard
Prometheus metrics export
Deployment instructions

🏗️ Modular Architecture

The TailscaleMCP server is built with a clean, modular architecture that separates concerns and makes the codebase maintainable and extensible.

Project Structure

src/tailscalemcp/
├── __init__.py
├── __main__.py
├── mcp_server.py          # Main server entry point
├── exceptions.py          # Custom exceptions
├── monitoring.py          # Monitoring and metrics collection
├── grafana_dashboard.py   # Grafana dashboard generation
├── taildrop.py           # Taildrop file sharing functionality
├── device_management.py  # Advanced device management
├── magic_dns.py          # MagicDNS and networking features
└── tools/                # Modular tool implementations
    ├── __init__.py
    ├── device_tools.py    # Device management tools
    ├── monitoring_tools.py # Monitoring and metrics tools
    ├── taildrop_tools.py  # Taildrop file sharing tools
    └── dns_tools.py       # DNS and MagicDNS tools

Tool Categories

🔧 Device Management Tools (`device_tools.py`)

List and search devices
Device authorization and management
SSH access configuration
Device tagging and grouping
Exit node and subnet router management

📊 Monitoring Tools (`monitoring_tools.py`)

Network status and health monitoring
Prometheus metrics export
Network topology visualization
Grafana dashboard creation and export
Health reports and analytics

📁 Taildrop Tools (`taildrop_tools.py`)

Secure file sharing between devices
Transfer management and monitoring
File expiration and cleanup
Transfer statistics and analytics

🌐 DNS Tools (`dns_tools.py`)

MagicDNS configuration
Custom DNS record management
DNS resolution and caching
Network policy management
ACL (Access Control List) management

Benefits of Modular Architecture

Maintainability: Each tool category is isolated and focused
Extensibility: Easy to add new tools without affecting existing functionality
Testability: Individual modules can be tested in isolation
Code Reusability: Tool modules can be reused across different contexts
Error Isolation: Issues in one module don't affect others

🛠️ Development

Prerequisites

Python 3.11+
uv (recommended) or pip
Docker (optional)

Setup Development Environment

# Clone the repository
git clone https://github.com/yourusername/tailscalemcp.git
cd tailscalemcp

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
make install-dev

# Setup pre-commit hooks
make pre-commit

# Or use the setup command
make setup

Development Commands

# Run tests
make test

# Run tests with coverage
make test-cov

# Run linting
make lint

# Format code
make format

# Run all checks
make all

# Build package
make build

# Run the server
make run

Docker Development

# Build development image
make docker-dev

# Run development container
make docker-run-dev

# Or use docker-compose
make dev-up

🧪 Testing

The project uses pytest with comprehensive test coverage:

# Run all tests
pytest

# Run with coverage
pytest --cov=tailscalemcp --cov-report=html

# Run specific test file
pytest tests/test_mcp_server.py

# Run with verbose output
pytest -v

📊 Code Quality

This project maintains high code quality standards:

Ruff: Fast Python linter and formatter
MyPy: Static type checking
Pytest: Comprehensive testing framework
Pre-commit: Automated code quality checks
Bandit: Security linting
Safety: Dependency vulnerability scanning

🚀 CI/CD Pipeline

The project includes a comprehensive CI/CD pipeline with:

Linting: Ruff, MyPy, and security checks
Testing: Multi-Python version testing with coverage
Security: Bandit and Safety scanning
Building: Package and Docker image building
Deployment: Automatic PyPI publishing on releases

🐳 Docker Support

Production Image

docker build -t tailscalemcp:latest .
docker run -p 8000:8000 tailscalemcp:latest

Development Image

docker build -f Dockerfile.dev -t tailscalemcp:dev .
docker run -p 8000:8000 -v $(pwd):/app tailscalemcp:dev

Docker Compose

# Production
docker-compose up -d

# Development
docker-compose --profile dev up -d

📚 API Reference

Core Classes

`TailscaleMCPServer`

Main server class for managing Tailscale networks.

server = TailscaleMCPServer(
    api_key: Optional[str] = None,
    tailnet: Optional[str] = None
)

Available Tools

list_devices(online_only: bool = False, filter_tags: List[str] = None)
get_device(device_id: str)
get_network_status()
get_dns_config()
list_acls(detailed: bool = False)
enable_exit_node(device_id: str, advertise_routes: List[str] = None)
disable_exit_node(device_id: str)
enable_subnet_router(device_id: str, subnets: List[str])
disable_subnet_router(device_id: str)

Exception Handling

from tailscalemcp.exceptions import (
    TailscaleMCPError,
    AuthenticationError,
    AuthorizationError,
    NotFoundError,
    ValidationError
)

try:
    device = await server._get_device_impl("invalid_id")
except NotFoundError as e:
    print(f"Device not found: {e.message}")

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Workflow

Setup development environment: make setup
Make your changes
Run tests: make test
Run linting: make lint
Format code: make format
Commit with conventional commits
Push and create PR

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Documentation: GitHub Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions

📚 Additional Documentation

Storage Backends Guide - Complete guide to FastMCP 2.13+ storage backends (DiskStore, Redis, MongoDB, etc.)
Mermaid Diagram Guide - How to view network topology diagrams
Status Tool Usage - Comprehensive guide to the status tool
Funnel Operations - Tailscale Funnel implementation details
Expansion Plan - Future features and roadmap

🙏 Acknowledgments

FastMCP for the excellent MCP framework with persistent storage support
Tailscale for the amazing networking platform
Ruff for fast Python tooling
py-key-value-aio for flexible storage backends
All contributors and users of this project

Made with ❤️ by the TailscaleMCP team