malaya-zemlya/tls-mcp

TLS MCP Server

A Model Context Protocol (MCP) server that provides a unified, user-friendly tool for TLS certificate analysis. No more copying PEM data between functions - everything happens in one clean interface! This tool has been written entirely via Claude Code, as a fun learning project.

🚀 Features

• All-in-One Interface: Single tool with flexible options for any certificate analysis need
• Smart Analysis: Automatically uses OpenSSL when available, falls back to Python cryptography
• Certificate Expiration Monitoring: Automatic expiration checking with human-friendly warnings
• Cipher Suite Analysis: Comprehensive TLS cipher suite and version support testing
• Security Grading: Automated security assessment with grades from A+ to F
• Flexible Options: Choose quick/detailed analysis, include/exclude PEM, enable/disable linting
• Zero PEM Copying: Analysis happens automatically without manual certificate handling
• Comprehensive Testing: Full test coverage with unit, integration, and real-world tests

🛠️ Tool Provided

fetch_certificate - All-in-One Certificate Analysis

Fetches and analyzes TLS certificates with flexible options - no need to copy PEM data between tools!

Parameters:

• hostname (required): Website hostname (e.g., "google.com")
• port (optional): Port number (default: 443)
• include_pem (optional): Include raw PEM certificate in output (default: false)
• analyze (optional): Analysis level - "none", "quick", or "detailed" (default: "quick")
• lint (optional): Run zlint compliance checking (default: false)
• use_openssl (optional): Use OpenSSL for analysis when available (default: true)
• analyze_ciphers (optional): Analyze supported cipher suites and TLS versions (default: false)
• cipher_scan_type (optional): Type of cipher scan - "quick" or "full" (default: "quick")

Analysis Options:

• Quick Analysis: Essential certificate info (subject, issuer, validity, SANs)
• Detailed Analysis: Full certificate details including extensions and key info
• Expiration Monitoring: Automatic expiration checking with smart warnings:
  • ✅ Valid certificates show time until expiration
  • 🟡 Certificates expiring within 30 days get yellow warning
  • ⚠️ Certificates expiring within 7 days get urgent warning
  • 🔴 Expired certificates show time since expiration
  • ⏳ Future-valid certificates show time until validity
• OpenSSL vs Cryptography: Automatically uses OpenSSL if available, falls back to Python cryptography

Examples:

• {"hostname": "google.com"} - Quick analysis only
• {"hostname": "github.com", "analyze": "detailed", "lint": true} - Detailed analysis + zlint
• {"hostname": "badssl.com", "analyze": "none", "include_pem": true} - Just fetch PEM

📋 Prerequisites

• Python 3.13+
• zlint (for certificate linting)
• OpenSSL (for certificate operations)

Install zlint

# macOS
brew install zlint

# Linux
go install github.com/zmap/zlint/v3/cmd/zlint@latest

# Or download from releases: https://github.com/zmap/zlint/releases

🔧 Installation

1. Clone and setup the project:

git clone <repository-url>
cd tls-mcp
python3.13 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

2. Install development dependencies (optional):

pip install -e ".[dev]"

3. Run tests to verify installation:

pytest tests/ -v

⚙️ Configuration

Add the following to your Claude Desktop configuration file:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "tls-mcp-server": {
      "command": "/path/to/your/tls-mcp/venv/bin/python",
      "args": [
        "/path/to/your/tls-mcp/tls_mcp_server/main.py"
      ],
      "env": {
        "PYTHONPATH": "/path/to/your/tls-mcp"
      }
    }
  }
}

Replace /path/to/your/tls-mcp with your actual project path.

🚦 Usage Examples

After configuration, restart Claude Desktop and try these commands:

Quick Certificate Analysis (Default)

"Analyze the certificate for github.com"

Detailed Analysis with Compliance Check

"Do a detailed analysis of google.com's certificate and run zlint on it"

Just Fetch Certificate (No Analysis)

"Get me the raw PEM certificate for badssl.com"

Compare Multiple Certificates

"Use the TLS certificate tool to analyze both google.com and github.com, then compare their key differences"

Security Assessment

"Use the TLS certificate tool to check if example.com uses secure certificate practices with full analysis and linting"

Cipher Suite Analysis

"Use the TLS certificate tool to analyze the cipher suites supported by github.com and give me a security assessment"

Comprehensive Security Analysis

"Use the TLS certificate tool to do a full security analysis of google.com including cipher suites, TLS versions, and certificate compliance"

Key Benefits:

• ✅ No PEM copying - Analysis happens automatically
• ✅ Flexible options - Choose what info you need
• ✅ Smart defaults - Works great out of the box
• ✅ OpenSSL integration - Uses the best available tools

🧪 Testing

Run the comprehensive test suite:

# Run all tests (including slow integration tests)
pytest tests/ -v

# Run only fast tests (excludes slow integration tests that require internet)
pytest tests/ -m "not slow" -v

# Run with coverage
pytest tests/ --cov=tls_mcp_server --cov-report=term-missing

# Run only unit tests
pytest tests/test_mcp_server.py -v

# Run only basic integration tests
pytest tests/test_integration.py -v

# Run real-world integration tests (requires internet and zlint)
pytest tests/test_google_integration.py -v

Test Coverage

• Unit Tests: Test the new unified interface with mocked dependencies
• Cipher Analysis Tests: Test cipher categorization, TLS version detection, and security grading
• Expiration Check Tests: Test certificate validity checking, duration formatting, and timezone handling
• Basic Integration Tests: Test server registration and tool options
• Real-World Integration Tests: Test full workflow with live Google certificate
• Error Handling: Test various failure scenarios
• Current Coverage: 34 passing tests with comprehensive coverage

📁 Project Structure

tls-mcp/
├── tls_mcp_server/
│   ├── __init__.py          # Package initialization
│   └── main.py              # MCP server implementation
├── tests/
│   ├── __init__.py              # Test package
│   ├── test_mcp_server.py       # Unit tests
│   ├── test_cipher_analysis.py  # Cipher analysis tests
│   ├── test_expiration_check.py # Expiration checking tests
│   └── test_integration.py      # Integration tests
├── pyproject.toml           # Project configuration
├── pytest.ini              # Test configuration
└── README.md               # This file

🔍 Architecture

The server is built using the MCP Python SDK with a modern, user-friendly design:

1. Single Tool Interface: One fetch_certificate tool with flexible options
2. Smart Analysis: Automatically chooses OpenSSL or Python cryptography
3. Async Operations: All operations are asynchronous for better performance
4. Error Handling: Comprehensive error handling with graceful fallbacks
5. Modular Helpers: Internal helper functions for different analysis methods
6. No PEM Juggling: Analysis happens automatically without manual PEM copying

🚨 Security Considerations

• Certificates are processed locally - no data is sent to external services
• Network connections use standard SSL/TLS libraries
• Temporary files are cleaned up after zlint operations
• Error messages don't expose sensitive system information

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass: pytest tests/ -v
5. Submit a pull request

📝 License

MIT License - see LICENSE file for details.

🆘 Troubleshooting

Common Issues

"zlint command not found"

• Install zlint using the instructions above
• Verify it's in your PATH: which zlint

"Failed to fetch certificate"

• Check your internet connection
• Verify the hostname is correct
• Some servers may block automated requests

"MCP server not appearing in Claude"

• Verify the configuration file path is correct
• Check that Python path in config points to your virtual environment
• Restart Claude Desktop after configuration changes

Debug Mode

Enable debug logging by setting the environment variable:

export PYTHONPATH="/path/to/tls-mcp"
python tls_mcp_server/main.py

🏷️ Version History

• v0.2.1: Added certificate expiration monitoring with human-friendly warnings and timezone handling
• v0.2.0: Major interface redesign with unified fetch_certificate tool, OpenSSL integration, cipher suite analysis, security grading
• v0.1.0: Initial release with basic certificate fetching, analysis, and linting