Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@amanahfy-ai-mcp Look up the campaign gaza-100k-in-72hrs"
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.
A production-ready Model Context Protocol (MCP) server that provides AI tools & resources with access to Amanahfy APIs & services. Built with TypeScript and following clean architecture principles.
Dual Transport Support: STDIO (Claude Desktop) and HTTP (testing/development)
Clean Architecture: 5-layer architecture with separation of concerns
CLI Tools: Command-line interface for direct API testing
Resource Access: URI-based resource references (campaign://slug, ip://address)
Type Safety: Full TypeScript implementation with Zod validation
Related MCP server: mcp-ip2location
Node.js (>=18.0.0): Download
Git: For version control
Claude Desktop: For MCP integration (Optional)
# Clone the repository
git clone <your-repo-url>
cd amanahfy-ai-mcp
# Install dependencies
npm install
# Build the project
npm run buildAdd to your Claude Desktop configuration (claude_desktop_config.json):
{
"mcpServers": {
"amanahfy-ai-mcp": {
"command": "node",
"args": [
"C:\\path\\to\\campaign-agent-mcp-server\\dist\\index.js"
],
"env": {
"TRANSPORT_MODE": "stdio"
}
}
}
}Restart Claude Desktop completely, then ask Claude:
"Look up the campaign gaza-100k-in-72hrs"
"What's the location of IP 8.8.8.8?"
Test functionality directly from the command line:
# Get campaign details
npm run cli -- get-campaign-details gaza-100k-in-72hrs
# With custom options
npm run cli -- get-campaign-details gaza-100k-in-72hrs --timeout 5000 --retries 1The server follows a clean 5-layer architecture:
├── CLI Layer (src/cli/) # Command-line interfaces
├── Tools Layer (src/tools/) # MCP tool definitions
├── Resources Layer (src/resources/) # MCP resource handlers
├── Controllers Layer (src/controllers/) # Business logic
├── Services Layer (src/services/) # External API integration
└── Utils Layer (src/utils/) # Shared utilitiesCreate a .env file in the project root:
# Transport Configuration
TRANSPORT_MODE=stdio
PORT=8000
DEBUG=false
NODE_ENV=production
# API Configuration
AMANAHFY_API_BASE=https://api.amanahfy.com/api
# Optional API Keys
# IPAPI_API_TOKEN=your_api_token_here# Development
npm run build # Compile TypeScript
npm run dev:stdio # Run in STDIO mode with debug
npm run dev:http # Run in HTTP mode with debug
# MCP Server Modes
npm run mcp:stdio # STDIO transport (for Claude Desktop)
npm run mcp:http # HTTP transport (for testing)
# Testing & Development
npm run cli # CLI mode
npm run test # Run tests
npm run lint # Run ESLint
npm run format # Format with Prettier
# Debugging
npm run mcp:inspect # Launch with MCP InspectorTest your MCP server with the official inspector:
# Launch server with inspector
npm run mcp:inspect
# Then open: http://localhost:3000/mcp# Test HTTP mode
npm run mcp:http
# Test specific endpoints
curl http://localhost:8000/mcp# Test campaign lookup
npm run cli -- get-campaign-details gaza-100k-in-72hrs
# Test IP lookup
npm run cli -- get-ip-details 8.8.8.8"Not valid JSON" error
Ensure no console output is interfering with STDIO mode
Check that TRANSPORT_MODE=stdio in Claude Desktop config
Module not found errors
Run npm run build after any code changes
Verify all dependencies are installed: npm install
API timeout errors
Check network connectivity
Increase timeout values in tool parameters
Verify API endpoints are accessible
Claude Desktop connection issues
Use absolute paths in config
Restart Claude Desktop completely after config changes
Check Claude Desktop logs for detailed error messages
Enable detailed logging:
DEBUG=true
NODE_ENV=developmentNeed help? Open an issue or check the troubleshooting section above.
Retrieves detailed information about a donation campaign from Amanahfy by campaign slug. Returns comprehensive campaign data including fundraising progress, organization details, timeline, and campaign features. Use this tool to get current information about active fundraising campaigns. Example slug: "gaza-100k-in-72hrs". Configure timeout and retries for reliability.
Inputs: campaignSlug (required), retries, timeout.
Retrieves detailed geolocation and network information for a public IP address (ipAddress). If no IP is provided, automatically uses the server's current public IP. Returns comprehensive location data including country, region, city, coordinates, timezone, and network details like ISP and organization. Use includeExtendedData to get additional information such as ASN, mobile/proxy detection (requires API token). Note: Cannot lookup private IPs (e.g., 192.168.x.x, 10.x.x.x). Powered by ip-api.com. Enable useHttps for secure connections (required for paid tier).
Inputs: useHttps, ipAddress, includeExtendedData.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 2 tools
The two tools are entirely unrelated in purpose: one handles IP geolocation and the other retrieves campaign details. There is zero overlap or ambiguity between them.
Both tools follow the same 'get_details' verb-noun pattern with clear prefixes ('ip' and 'campaign'), creating a consistent and predictable naming convention.
With only 2 tools, the server feels thin. While each tool is distinct, the low count is borderline for a server that appears to cover two separate domains.
Each domain is only minimally covered: IP lookup has no additional operations beyond details, and campaigns similarly lack listing or mutation endpoints. The server leaves significant gaps for any broader workflow.
Utility tools for AI agents: hashing, text stats, validation, DNS, currency, GEO audits.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
Marketing intelligence API for AI agents. Real campaign data, not LLM guesses.
