The Aleph MCP
The Aleph MCP is a Model Context Protocol (MCP) server that provides LLMs with powerful network intelligence capabilities through The Aleph API. Connect Claude Desktop to real-time PTR records, ASN data, traceroute analysis, and network monitoring.
🌐 Live API: thealeph.ai | 📖 Full Docs: API Documentation
🚀 Quick Installation
Method 1: NPM Registry (Recommended)
# Once published to npm
npm install -g thealeph-mcp
thealeph-mcp --setup
Method 2: Install from GitHub
# Install directly from GitHub repository
npm install -g https://github.com/NU-AquaLab/thealeph-mcp.git
# Setup Claude Desktop (interactive)
thealeph-mcp --setup
# Test everything works
thealeph-mcp --test-all
Method 3: Clone and Install
# Clone the repository
git clone https://github.com/NU-AquaLab/thealeph-mcp.git
cd thealeph-mcp
# Install globally
npm install -g .
# Setup Claude Desktop
thealeph-mcp --setup
✅ Verify Installation
After installation, restart Claude Desktop and ask:
"What tools do you have available?"
You should see 13 Aleph tools listed! Then try:
"Check the health of The Aleph system"
"Query the PTR record for IP 8.8.8.8"
"What are the regex patterns for ASN 15169?"
🛠️ Features
🌐 Network Intelligence Tools
The Aleph MCP provides 13 powerful tools for network analysis:
Monitoring Tools (5)
- Health Check - System status and availability
- Current Statistics - API usage stats for last N days
- Daily Statistics - Statistics for specific date
- Summary Statistics - Quick usage summary
- Export Statistics - Export monitoring data (JSON/CSV)
ASN Analysis Tools (5)
- ASN Classifications - Classification data for ASNs
- ASN Regex Patterns - PTR parsing patterns for ASNs
- ASN Hints - Geographic and network hints
- ASN Infrastructure Mapping - Infrastructure location mapping
- ASN Hint Mapping - Hint-based location mapping
PTR Query Tools (2)
- Query PTR - Single PTR record query with network intelligence
- Batch Query PTR - Multiple PTR queries (up to 100)
Traceroute Tools (1)
- Traceroute Mapper - Enrich traceroute with network intelligence
📊 Data Sources
- PTR Records: Reverse DNS lookups with geographic intelligence
- ASN Data: Autonomous System classifications and patterns
- Traceroute Analysis: Hop-by-hop network intelligence
- Monitoring: Real-time API usage statistics
- API: Production deployment at thealeph.ai
🔧 CLI Commands
# Start MCP server (for Claude Desktop)
thealeph-mcp
# Interactive Claude Desktop setup
thealeph-mcp --setup
# Test API connection
thealeph-mcp --test
# Run full test suite
thealeph-mcp --test-all
# Show current configuration
thealeph-mcp --config
# Show help
thealeph-mcp --help
📋 Requirements
- Node.js: 18.0.0 or higher (Download)
- npm: Latest version (comes with Node.js)
- Claude Desktop: Latest version with MCP support
- Network: Internet connection to reach The Aleph API
Check Requirements
# Verify you have the right versions
node --version # Should be v18.0.0+
npm --version # Any recent version
which thealeph-mcp # Should show path after installation
🔧 Configuration & Setup
Automatic Configuration (Recommended)
# Interactive setup - detects your system automatically
thealeph-mcp --setup
This command will:
- ✅ Automatically locate your The Aleph MCP installation
- ✅ Verify the installation is working correctly
- ✅ Detect your operating system (macOS/Windows/Linux)
- ✅ Find your Claude Desktop configuration file
- ✅ Configure Claude Desktop with the correct absolute path
- ✅ Show you exactly where everything was installed
Manual Configuration
If automatic setup doesn't work:
1. Find Your Claude Desktop Config File
| OS | Location |
|---|---|
| macOS | ~/Library/Application\ Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
2. Add The Aleph MCP Configuration
Add the following configuration to your Claude Desktop config file:
{
"mcpServers": {
"thealeph": {
"command": "thealeph-mcp"
}
}
}
This uses the default Aleph server at https://thealeph.ai.
Environment Variables
# Set custom API URL (optional)
export THEALEPH_API_URL=https://thealeph.ai
# Windows PowerShell:
$env:THEALEPH_API_URL="https://thealeph.ai"
📖 Usage Examples
Once configured, you can use The Aleph tools in Claude Desktop:
Basic Health Check
"Check the health of The Aleph system"
PTR Record Queries
"Query the PTR record for IP address 8.8.8.8"
"What network information can you find for dns.google?"
Batch PTR Queries
"Query PTR records for these IPs: 8.8.8.8, 1.1.1.1, and 9.9.9.9"
ASN Analysis
"What are the regex patterns used by Google's ASN 15169?"
"Show me the infrastructure mapping for ASN 15169"
Traceroute Analysis
"Here's my traceroute output, enrich it with network intelligence: [paste traceroute]"
Network Research
"What geographic hints are available for Cloudflare's ASN 13335?"
"Compare the classifications between ASN 15169 (Google) and ASN 32934 (Meta)"
🐛 Troubleshooting
Installation Issues
| Problem | Solution |
|---|---|
| "npm: command not found" | Install Node.js from nodejs.org |
| "EACCES: permission denied" | Use npm config set prefix ~/.npm-global and update PATH |
| "Cannot find module" | Reinstall: npm uninstall -g thealeph-mcp && npm install -g https://github.com/NU-AquaLab/thealeph-mcp.git |
| Package not found after install | Check npm global path: npm root -g |
Claude Desktop Issues
| Problem | Diagnosis | Solution |
|---|---|---|
| Claude doesn't see Aleph tools | Config file issue | Run thealeph-mcp --setup again |
| "MCP server disconnected" | Server crash | Check logs, restart Claude Desktop |
| Tools listed but don't work | API connectivity | Test with thealeph-mcp --test |
| Setup command hangs | Permission/path issue | Run with sudo or fix npm permissions |
Debug Commands
# Check what's actually installed
npm list -g thealeph-mcp
# Find installation path
which thealeph-mcp
# Test server directly
node $(npm root -g)/thealeph-mcp/src/server.js --version
# Validate Claude Desktop config
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .
# Test API server
curl https://thealeph.ai/monitoring/health
Log Files
Check these locations for error logs:
| OS | Log Location |
|---|---|
| macOS | ~/Library/Logs/Claude/ |
| Windows | %LOCALAPPDATA%\Claude\logs\ |
| Linux | ~/.local/share/Claude/logs/ |
For more detailed troubleshooting, see docs/TROUBLESHOOTING.md.
📄 License
MIT License - see LICENSE file for details.
🤝 Contributing
Contributions are welcome! Please see our Contributing Guide for details.
📚 Related Projects
- The Aleph Web App: thealeph.ai
- The Aleph API Docs: API Documentation
- Model Context Protocol: MCP Specification
The Aleph MCP - Bringing network intelligence to conversational AI 🌐✨