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

🔧 Installation

1. Clone and setup the project:

2. Install development dependencies (optional):

3. Run tests to verify installation:

⚙️ Configuration

Add the following to your Claude Desktop configuration file:

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

Replace

🚦 Usage Examples

After configuration, restart Claude Desktop and try these commands:

Quick Certificate Analysis (Default)

Detailed Analysis with Compliance Check

Just Fetch Certificate (No Analysis)

Compare Multiple Certificates

Security Assessment

Cipher Suite Analysis

Comprehensive Security Analysis

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:

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

🔍 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:

🏷️ 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