MCP Ahrefs
Ahrefs MCP Server for SAAGA
Quick Start with AI Assistant
Need help getting started? Have your AI coding assistant guide you!
Simply tell your AI assistant: "I have a MCP Ahrefs project. Please read and follow WORKING_WITH_SAAGA_PROMPT.md to help me understand and work with this MCP server."
For quick reference, the .ai-prompts.md file contains a condensed version of key patterns.
For detailed technical documentation, see docs/DECORATOR_PATTERNS.md.
Testing with MCP Inspector
Ready to test your MCP server? The MCP Inspector Guide provides:
- Step-by-step setup instructions with virtual environment troubleshooting
- Test examples for all included tools
- JSON mode instructions for parallel tools
- Common issues and solutions
Quick start:
Testing with Claude CLI
This project includes a convenient test script for testing your MCP server with Claude:
The script automatically:
- Uses the generated
mcp.integration_test.json
configuration (created by cookiecutter) - Runs Claude with the Sonnet model
- Includes proper MCP configuration flags
- Provides colored output for better readability
MCP Integration Testing
This project includes comprehensive integration tests that validate tools work correctly with real MCP client interactions:
Running Integration Tests
What's Tested
The integration tests validate:
- Tool Discovery: All tools are discoverable with correct schemas (no "kwargs" parameters)
- Parameter Conversion: String parameters from MCP are converted to appropriate types
- Error Handling: Invalid parameters and exceptions return proper error responses
- SAAGA Integration: Decorators work correctly in the full MCP protocol flow
- Protocol Compliance: Tools work with real MCP client connections
Generating Tests for New Tools
When you add a new tool, generate integration tests for it:
Integration vs Unit Tests
- Unit Tests (
test_decorators.py
): Test SAAGA decorators in isolation - Integration Tests (
test_mcp_integration.py
): Test complete MCP protocol flow with real client
Run both test suites to ensure full coverage:
Overview
This MCP server was generated using the SAAGA MCP Server Cookie Cutter template. It includes:
- FastMCP Integration: Modern MCP framework with dual transport support
- SAAGA Decorators: Automatic exception handling, logging, and parallelization
- Platform-Aware Configuration: Cross-platform configuration management
- Streamlit Admin UI: Web-based configuration and monitoring interface
- SQLite Logging: Comprehensive logging with database persistence
Installation
Prerequisites
- Python 3.12 or higher
- UV - An extremely fast Python package manager
Install from Source
Development Installation
Usage
Running the MCP Server
The server can be run in two modes:
1. STDIO Mode (for MCP clients like Claude Desktop)
2. SSE Mode (for web-based clients)
Command Line Options
Available options:
--transport
: Choose between "stdio" (default) or "sse"--host
: Host to bind to for SSE transport (default: 127.0.0.1)--port
: Port to bind to for SSE transport (default: 3001)--log-level
: Logging level - DEBUG, INFO, WARNING, ERROR (default: INFO)
MCP Client Configuration
Claude Desktop Configuration
Add the following to your Claude Desktop MCP settings (claude_desktop_config.json
):
Advanced Configuration Options
Using with System Python (Alternative)
Using with uv tool
Configuration File Locations
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
- Windows:
%APPDATA%/Claude/claude_desktop_config.json
Admin UI
Launch the Streamlit admin interface:
Dashboard
The dashboard provides:
- Real-time server status monitoring
- Project information and configuration overview
- Quick access to common actions
- System resource usage
Configuration Editor
The configuration editor features:
- Live configuration editing with validation
- Diff preview showing pending changes
- Export/import functionality (JSON & YAML formats)
- Reset to defaults with confirmation dialog
- Automatic server restart notifications
Log Viewer
The log viewer includes:
- Date range filtering for historical analysis
- Status filtering (success/error/all)
- Tool-specific filtering
- Export capabilities for further analysis
- Real-time log updates
AI Assistant Instructions
When working with this MCP Ahrefs MCP server in an AI coding assistant (like Claude, Cursor, or GitHub Copilot):
Understanding the Server Architecture
This server uses SAAGA decorators that automatically wrap all MCP tools with:
- Exception handling: All errors are caught and returned as structured error responses
- Comprehensive logging: All tool invocations are logged with timing and parameters
- Optional parallelization: Tools marked for parallel execution run concurrently
Key Points for AI Assistants
- Tool Registration Pattern: Tools are registered with decorators already applied. Do NOT manually wrap tools with decorators - this is handled automatically in
server/app.py
. - Parameter Types: MCP passes all parameters as strings from the client. Ensure your tools handle type conversion:
- Error Handling: Tools can raise exceptions freely - the exception_handler decorator will catch them and return proper error responses.
- Async Support: Both sync and async tools are supported. The decorators automatically detect and handle both patterns.
- Logging: Check logs at the platform-specific data directory for debugging:
- macOS:
~/Library/Application Support/mcp_ahrefs/logs.db
- Linux:
~/.local/share/mcp_ahrefs/logs.db
- Windows:
%APPDATA%/mcp_ahrefs/logs.db
- macOS:
Common Tasks
Adding a new tool:
Testing with MCP Inspector:
Debugging a tool:
- Check the SQLite logs for error messages
- Run with
--log-level DEBUG
for verbose output - Test directly with MCP Inspector to see parameter handling
Important Implementation Notes
- The server uses the standard MCP SDK (
from mcp.server.fastmcp import FastMCP
) - Function signatures are preserved through careful decorator implementation
- The
register_tools()
function inserver/app.py
handles all decorator application - Tools should return JSON-serializable Python objects (dict, list, str, int, etc.)
Configuration
Configuration files are stored in platform-specific locations:
- macOS:
~/Library/Application Support/mcp_ahrefs/
- Linux:
~/.local/share/mcp_ahrefs/
- Windows:
%APPDATA%/mcp_ahrefs/
Configuration Options
log_level
: Logging level (INFO)log_retention_days
: Days to retain logs (30)server_port
: HTTP server port (3001)
Development
Project Structure
Adding New Tools
- Create a new Python file in
mcp_ahrefs/tools/
- Define your tool function
- Import and register it in
server/app.py
Example:
Running Tests
Code Quality
This project uses several code quality tools:
SAAGA Decorators
This server automatically applies three key decorators to your MCP tools:
- Exception Handler: Graceful error handling with logging
- Tool Logger: Comprehensive logging to SQLite database
- Parallelize: Optional parallel processing for compute-intensive tools
Logging
Logs are stored in a SQLite database with the following schema:
timestamp
: When the tool was calledtool_name
: Name of the MCP toolduration_ms
: Execution time in millisecondsstatus
: Success/failure statusinput_args
: Tool input argumentsoutput_summary
: Summary of tool outputerror_message
: Error details (if any)
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Run the test suite
- Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
For issues and questions:
- Create an issue on GitHub
- Check the documentation in the
docs/
directory - Review the test suite for usage examples
Acknowledgments
- FastMCP for the MCP framework
- SAAGA for the decorator patterns
- Cookiecutter for the templating system
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Enables integration with Ahrefs SEO tools and services through MCP protocol. Provides automated exception handling, comprehensive logging, and parallel processing capabilities for SEO data analysis and operations.
Related MCP Servers
- AsecurityFlicenseAqualityBuilt as a Model Context Protocol (MCP) server that provides advanced web search, content extraction, web crawling, and scraping capabilities using the Firecrawl API.Last updated -41Python
- -securityFlicense-qualityProvides SEO automation with tools for keyword research, SERP analysis, and competitor analysis through Google Ads API integration, enabling AI assistants to access these capabilities via MCP.Last updated -22JavaScript
- -securityFlicense-qualityMCP server that enables AI assistants to perform SEO automation tasks including keyword research, SERP analysis, and competitor analysis through Google Ads API integration.Last updated -1
- AsecurityFlicenseAqualityA Cursor MCP server that analyzes web pages for SEO issues and validates structured data schemas within your codebase without requiring browser extensions.Last updated -12JavaScript