mihailozepina/aimfox-mcp-server

Aimfox MCP Server

A comprehensive Model Context Protocol (MCP) server for Aimfox LinkedIn automation, providing seamless integration with AI tools like Claude Desktop, automation platforms, and custom applications.

🚀 Features

• 🎯 Complete Aimfox API Coverage - 37+ tools covering all major Aimfox functionality
• 🔄 Dual Mode Support - Run as stdio MCP server or HTTP streaming server
• 🛡️ Production Ready - Authentication, rate limiting, CORS, health checks
• ⚡ Type Safe - Full TypeScript implementation with Zod validation
• 🌐 Universal Compatibility - Works with Claude Desktop, VS Code, Make.com, Clay, n8n, and more
• 📦 Easy Installation - Simple npm package with global CLI command

📋 Table of Contents

• Quick Start
• Installation
• Usage Modes
• Available Tools
• Configuration
• Deployment
• Integration Examples
• Integration Guides
• API Reference
• Development
• Troubleshooting

⚡ Quick Start

For Claude Desktop Users

1. Get your Aimfox API key from your Aimfox account dashboard

2. Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

   {
     "mcpServers": {
       "aimfox": {
         "type": "http",
         "url": "https://mcp.aimfox.com/mcp",
         "headers": {
           "Authorization": "Bearer your-aimfox-api-key-here"
         }
       }
     }
   }
   

3. Restart Claude Desktop and start using Aimfox tools naturally:

   • "Show me my Aimfox campaigns"
   • "Search for leads with the label 'qualified'"
   • "Create a new message template"

For VS Code Users

1. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Run: MCP: Add Server → Select HTTP Server
3. Enter URL: https://mcp.aimfox.com/mcp
4. Add Authorization header: Bearer your-aimfox-api-key
5. Name your server: "Aimfox MCP"
6. Select Global for all projects
7. Start using Aimfox tools in GitHub Copilot Chat!

� How It Works

Aimfox MCP Server is a hosted service that connects your AI tools directly to the Aimfox API. No installation required!

✅ Hosted Service Benefits

• Zero setup - Just add the URL and your API key
• Always updated - Latest features appear automatically
• Enterprise-grade - Professional hosting with 99.9% uptime
• Secure - Your API key is used directly for authentication
• Cross-platform - Works with any MCP-compatible tool

🔗 Connection Details

• Server URL: https://mcp.aimfox.com/mcp
• Authentication: Your Aimfox API key via Authorization header
• Protocol: HTTP with MCP streaming support
• Rate limits: Based on your Aimfox subscription

📦 Self-Hosting Option

For advanced users who prefer self-hosting:

# Install and run locally
npm install -g aimfox-mcp-server
AIMFOX_API_KEY=your-key aimfox-mcp-server --http

Self-hosting provides:

• Full control over the server
• Custom deployment options
• Development and testing capabilities

� Supported Integrations

🤖 AI Tools & Assistants

• Claude Desktop - Native MCP support
• VS Code with GitHub Copilot - Built-in MCP integration
• Custom AI applications - Any MCP-compatible client

🔗 Automation Platforms

• Make.com - HTTP API integration
• n8n - Workflow automation
• Clay - Data enrichment workflows
• Zapier - Trigger-based automation

🛠️ Developer Tools

• Custom applications - Direct HTTP API access
• Workflow builders - MCP protocol integration
• AI agent frameworks - Tool augmentation

📋 Connection Methods

MCP Protocol (Recommended)

URL: https://mcp.aimfox.com/mcp
Method: HTTP with MCP streaming
Auth: Authorization: Bearer {your-aimfox-api-key}

Direct HTTP API

# Example API call
curl -X POST https://mcp.aimfox.com/mcp \
  -H "Authorization: Bearer your-aimfox-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_campaigns","arguments":{"api_key":"your-aimfox-api-key"}},"id":1}'

🛠️ Available Tools

👥 Account Management

📈 Campaign Operations

🎯 Lead Management

🏷️ Labels & Organization

📝 Message Templates

💬 Conversations

📊 Analytics & Reporting

🔗 Webhooks & Integration

⚙️ Configuration

Environment Variables

Configuration File

Create aimfox-config.json in your working directory:

{
  "aimfox": {
    "apiKey": "your-aimfox-api-key",
    "baseUrl": "https://api.aimfox.com/v1"
  },
  "server": {
    "port": 3000,
    "apiKey": "your-server-secret",
    "cors": {
      "origins": ["http://localhost:3000", "https://yourdomain.com"]
    }
  }
}

🌐 Deployment

Railway Deployment

The project includes a comprehensive railway.toml configuration with:

• ✅ Autoscaling (1-3 replicas based on CPU/memory)
• ✅ Health checks on /health endpoint
• ✅ CORS configuration for MCP compatibility
• ✅ DNS rebinding protection for security
• ✅ Staging and production environments

Deployment Steps:

1. Connect your repository to Railway (railway.app)
2. Set environment variables in Railway dashboard:

   AIMFOX_API_KEY=your-aimfox-api-key
   MCP_API_KEY=your-server-secret
   NODE_ENV=production
   

3. Railway automatically uses the railway.toml configuration
4. Deploy and monitor - Railway handles autoscaling and health checks

Using Railway CLI:

npm install -g @railway/cli
railway login
railway init

# Deploy to staging first
railway up --environment staging

# Test the deployment
RAILWAY_URL=https://your-app.railway.app npm run test:deployment

# Deploy to production after testing
railway up --environment production

Railway Features Enabled:

• Resource Management: 512MB RAM, 0.5 CPU cores
• Auto-scaling: Scales based on 70% CPU, 80% memory thresholds
• Health Monitoring: 30-second intervals with automatic restarts
• CORS Headers: Pre-configured for MCP protocol compatibility

▲ Vercel Deployment (Fastest)

Global edge deployment - Instant HTTPS, custom domains, and automatic scaling.

The project includes vercel.json configuration with:

• ✅ Serverless functions - Automatic scaling with zero cold starts
• ✅ Global CDN - Deploy to 100+ edge locations worldwide
• ✅ HTTPS by default - Automatic SSL certificates
• ✅ Custom domains - Connect your own domain easily
• ✅ Environment variables - Secure configuration management

One-Click Deployment:

1. Click "Deploy with Vercel" button above
2. Sign in to Vercel (connect GitHub if needed)
3. Configure environment (optional):

   ALLOWED_HOSTS=your-custom-domain.vercel.app
   NODE_ENV=production
   

4. Deploy! - Vercel automatically builds and deploys

Manual Deployment:

# Install Vercel CLI
npm install -g vercel

# Deploy from project directory
cd aimfox-mcp-server
vercel --prod

# Set custom domain (optional)
vercel domains add your-domain.com

Usage after deployment:

# Test your deployment
curl https://your-app.vercel.app/health

# Use in MCP clients
{
  "url": "https://your-app.vercel.app/mcp",
  "headers": {
    "Authorization": "Bearer your-aimfox-api-key"
  }
}

Heroku Deployment

The project includes a Procfile for Heroku deployment that automatically starts the HTTP server:

web: npm run start:http

Deployment Steps:

1. Install Heroku CLI and login to your account
2. Create Heroku app:

   heroku create your-aimfox-mcp-server
   

3. Set environment variables:

   heroku config:set AIMFOX_API_KEY=your-aimfox-api-key
   heroku config:set MCP_API_KEY=your-server-secret
   heroku config:set NODE_ENV=production
   

4. Deploy:

   git push heroku main
   

Heroku automatically:

• ✅ Detects Node.js via package.json
• ✅ Runs npm install to install dependencies
• ✅ Builds TypeScript via npm run build
• ✅ Starts HTTP server via Procfile

Test your deployment:

# Check if server is running
curl https://your-aimfox-mcp-server.herokuapp.com/health

# Test MCP endpoint
curl -X POST https://your-aimfox-mcp-server.herokuapp.com/mcp \
  -H "Authorization: Bearer your-server-secret" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

Docker & Docker Compose Deployment

The project includes comprehensive Docker support with:

• ✅ Multi-stage Dockerfile with builder and production stages
• ✅ Docker Compose for production deployment
• ✅ Development override for live development
• ✅ Environment configuration via .env files

Production Deployment with Docker Compose

1. Create environment file:

   cp .env.example .env
   # Edit .env with your API keys
   

2. Deploy with Docker Compose:

   # Production deployment
   docker-compose up -d
   
   # With Nginx reverse proxy (optional)
   docker-compose --profile production up -d
   
   # With Redis caching (optional)
   docker-compose --profile redis up -d
   

3. Test the deployment:

   curl http://localhost:3000/health
   

Development with Docker Compose

For live development with hot reloading:

# Start development environment
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

# Features enabled:
# ✅ Live code reloading (no rebuilds needed)
# ✅ Debug port exposed (9229)
# ✅ Source code mounted
# ✅ Development logging

Manual Docker Build

# Build the image
docker build -t aimfox-mcp-server .

# Run production container
docker run -p 3000:3000 \
  -e AIMFOX_API_KEY=your-key \
  -e MCP_API_KEY=your-secret \
  -e NODE_ENV=production \
  aimfox-mcp-server

Docker Features

• Multi-stage build: Optimized production image size
• Security: Non-root user, proper file ownership
• Health checks: Automatic container health monitoring
• Environment defaults: Pre-configured CORS and security settings
• Networks: Isolated container networking
• Volumes: Persistent data and log storage

Nginx Reverse Proxy (Production)

The project includes production-ready nginx configuration with:

• ✅ HTTPS enforcement - HTTP automatically redirects to HTTPS
• ✅ SSL/TLS termination - Modern cipher suites and protocols
• ✅ Rate limiting - API protection (10 req/s with burst)
• ✅ Security headers - XSS, CSRF, HSTS protection
• ✅ MCP streaming support - WebSocket upgrades for MCP protocol
• ✅ CORS configuration - Pre-configured for cross-origin requests

SSL Certificate Setup:

# Development (self-signed)
openssl req -x509 -newkey rsa:4096 -keyout ssl/key.pem -out ssl/cert.pem -days 365 -nodes \
  -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"

# Production (Let's Encrypt)
sudo certbot certonly --standalone -d your-domain.com
sudo cp /etc/letsencrypt/live/your-domain.com/fullchain.pem ssl/cert.pem
sudo cp /etc/letsencrypt/live/your-domain.com/privkey.pem ssl/key.pem

Deploy with nginx:

# Set up SSL certificates first (see ssl/README.md)
# Then deploy with nginx reverse proxy
docker-compose --profile production up -d

# Access via:
# HTTP: http://localhost (redirects to HTTPS)
# HTTPS: https://localhost (with SSL)

Nginx provides:

• Load balancing - Ready for multiple MCP server instances
• SSL termination - Handles HTTPS encryption/decryption
• Rate limiting - Protects against API abuse
• Security headers - Enterprise-grade security features
• Access logs - Detailed request logging for monitoring

🔌 Integration Examples

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "aimfox": {
      "type": "http",
      "url": "https://mcp.aimfox.com/mcp",
      "headers": {
        "Authorization": "Bearer your-aimfox-api-key"
      }
    }
  }
}

Then restart Claude Desktop and start using Aimfox tools naturally in your conversations!

VS Code with GitHub Copilot

Step-by-step integration with VS Code's native MCP support:

Prerequisites

• VS Code 1.102+ with GitHub Copilot extension
• Aimfox API key from your account dashboard

Setup Instructions

1. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Search and select: MCP: Add Server
3. Choose: HTTP Server
4. Enter server details:
   • URL: https://mcp.aimfox.com/mcp
   • Name: Aimfox MCP
   • Scope: Global (available in all projects)
5. Add Authentication:
   • Header: Authorization
   • Value: Bearer your-aimfox-api-key
6. Confirm and trust the server when prompted

Using Aimfox Tools in VS Code

1. Open GitHub Copilot Chat (Ctrl+Cmd+I / Ctrl+Alt+I)
2. Switch to Agent mode from the dropdown
3. Enable Aimfox tools in the Tools panel
4. Ask naturally:
   • "What campaigns are currently running in Aimfox?"
   • "Show me leads labeled as 'qualified'"
   • "Create a follow-up message template"
5. Approve tool usage when prompted

VS Code Features

• ✅ Native integration - No extensions needed beyond Copilot
• ✅ Tool picker - Enable/disable specific Aimfox tools
• ✅ Direct tool invocation - Use #tool_name syntax
• ✅ Resource browsing - Explore Aimfox data as context
• ✅ Automatic sync - Settings sync across devices
• ✅ Security prompts - Review actions before execution### Make.com Integration

1. Add HTTP module in Make.com scenario
2. Configure the request:
   • URL: https://mcp.aimfox.com/mcp
   • Method: POST
   • Headers:
     • Authorization: Bearer your-aimfox-api-key
     • Content-Type: application/json
3. Use MCP JSON-RPC format in request body:

   {
     "jsonrpc": "2.0",
     "method": "tools/call",
     "params": {
       "name": "list_campaigns",
       "arguments": {
         "api_key": "your-aimfox-api-key"
       }
     },
     "id": 1
   }
   

Clay Integration

1. Add HTTP API source in Clay
2. Configure the endpoint:
   • URL: https://mcp.aimfox.com/mcp
   • Method: POST
   • Headers: Authorization: Bearer your-aimfox-api-key
3. Use in Clay workflows to enrich data with Aimfox information
4. Example use cases:
   • Fetch lead details for LinkedIn profiles
   • Check campaign status for prospects
   • Retrieve conversation history

Custom JavaScript Application

class AimfoxMCPClient {
  constructor(serverUrl, apiKey) {
    this.serverUrl = serverUrl;
    this.apiKey = apiKey;
    this.sessionId = null;
  }

  async initialize() {
    const response = await fetch(`${this.serverUrl}/mcp`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Accept: "application/json, text/event-stream",
        "X-API-Key": this.apiKey,
      },
      body: JSON.stringify({
        jsonrpc: "2.0",
        method: "initialize",
        params: {
          protocolVersion: "2024-11-05",
          capabilities: { tools: {} },
          clientInfo: { name: "my-app", version: "1.0.0" },
        },
        id: 1,
      }),
    });

    this.sessionId = response.headers.get("mcp-session-id");
    return response.json();
  }

  async listAccounts() {
    return this.callTool("list_accounts", {
      api_key: "user-aimfox-api-key",
    });
  }

  async callTool(name, args) {
    const response = await fetch(`${this.serverUrl}/mcp`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Accept: "application/json, text/event-stream",
        "X-API-Key": this.apiKey,
        "mcp-session-id": this.sessionId,
      },
      body: JSON.stringify({
        jsonrpc: "2.0",
        method: "tools/call",
        params: { name, arguments: args },
        id: Date.now(),
      }),
    });

    return response.json();
  }
}

// Usage
const client = new AimfoxMCPClient("http://localhost:3000", "your-server-key");
await client.initialize();
const accounts = await client.listAccounts();

📚 API Reference

Tool Parameters

All tools require an api_key parameter containing the user's Aimfox API key.

Example Tool Call

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_leads",
    "arguments": {
      "api_key": "your-aimfox-api-key",
      "filters": {
        "labels": ["qualified"],
        "limit": 10
      }
    }
  },
  "id": 1
}

HTTP Authentication

Header-based (Recommended)

curl -X POST http://localhost:3000/mcp \
  -H "X-API-Key: your-server-secret" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list", "id": 1}'

URL-based

curl -X POST http://localhost:3000/mcp/your-server-secret \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list", "id": 1}'

Health Endpoints

Health Check

curl http://localhost:3000/health

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "uptime": 3600,
  "memory": { "heapUsed": 50000000 },
  "sessions": 5
}

Readiness Check

curl -H "X-API-Key: your-server-secret" \
     http://localhost:3000/ready

🔨 Development

Prerequisites

• Node.js 18+
• npm or yarn
• TypeScript

Setup

git clone https://github.com/mihailozepina/aimfox-mcp-server
cd aimfox-mcp-server
npm install

Development Commands

npm run dev          # Start stdio server in development
npm run dev:http     # Start HTTP server in development
npm run build        # Build TypeScript to JavaScript
npm run test         # Run comprehensive test suite
npm run test:deployment # Test deployed server
npm run lint         # Lint code

Project Structure

aimfox-mcp-server/
├── src/
│   ├── index.ts              # Stdio server entry point
│   ├── http-server.ts        # HTTP server entry point
│   ├── server.ts             # Shared MCP server factory
│   ├── tools/                # Tool implementations
│   │   ├── accounts.ts       # Account management tools
│   │   ├── campaigns.ts      # Campaign tools
│   │   ├── leads.ts          # Lead management tools
│   │   ├── labels.ts         # Label tools
│   │   ├── blacklist.ts      # Blacklist tools
│   │   ├── templates.ts      # Template tools
│   │   ├── conversations.ts  # Conversation tools
│   │   ├── analytics.ts      # Analytics tools
│   │   ├── webhooks.ts       # Webhook tools
│   │   └── tokens.ts         # Token tools
│   └── utils/
│       ├── api-client.ts     # Aimfox API client
│       └── types.ts          # TypeScript type definitions
├── tests/
│   ├── run-all-tests.js      # Comprehensive test suite
│   ├── test-deployment.js    # Deployment testing
│   ├── test-http.js          # HTTP server tests
│   ├── test-http-simple.js   # Simple HTTP tests
│   └── test-stdio.js         # Stdio server tests
├── ssl/
│   └── README.md             # SSL certificate setup guide
├── build/                    # Compiled JavaScript (generated)
├── .env.example              # Environment variables template
├── docker-compose.yml        # Docker Compose production config
├── docker-compose.dev.yml    # Docker Compose development config
├── nginx.conf                # Nginx reverse proxy configuration
├── Dockerfile                # Docker container config
├── Procfile                  # Heroku deployment config
├── railway.toml              # Railway deployment config
├── LICENSE                   # MIT license file
├── package.json              # Node.js project config
└── tsconfig.json             # TypeScript config

Adding New Tools

1. Create tool file in src/tools/
2. Define Zod schemas for validation
3. Implement tool functions using the API client
4. Register tools in the tool file
5. Import and register in src/server.ts

Example:

import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { makeAimfoxRequest } from "../utils/api-client.js";

export const myToolSchema = z.object({
  api_key: z.string().describe("Aimfox API key"),
  param: z.string().describe("Tool parameter"),
});

export function registerMyTools(server: McpServer): void {
  server.tool(
    "my_tool",
    "Description of my tool",
    myToolSchema.shape,
    async ({ api_key, param }) => {
      const data = await makeAimfoxRequest("/endpoint", {
        apiKey: api_key,
        data: { param },
      });

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(data, null, 2),
          },
        ],
      };
    }
  );
}

🐛 Troubleshooting

Common Issues

"Invalid or missing session ID" Error

This error appears when accessing /mcp in a browser. The MCP endpoint requires proper MCP protocol messages, not HTTP GET requests.

Solution: Use the root endpoint / for documentation or proper MCP clients.

"Connection refused" in Claude Desktop

Check that the server is running and the path in your config is correct.

Solution:

# Test the server
aimfox-mcp-server &
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | nc localhost 8080

"Unauthorized" HTTP errors

Your API key configuration might be incorrect.

Solution: Verify environment variables:

echo $AIMFOX_API_KEY  # Should show your Aimfox API key
echo $MCP_API_KEY     # Should show your server secret

Rate limiting errors

Aimfox API has rate limits per account.

Solution: Implement exponential backoff or reduce request frequency.

Debug Mode

Enable debug logging:

DEBUG=aimfox:* aimfox-mcp-server

Testing

Local Testing:

# Run comprehensive test suite
npm test

# Test specific components
npm run test:deployment  # Test deployed server

# Manual testing
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npm start

# HTTP endpoint testing
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: test-key" \
  -d '{"method":"tools/list","id":1}'

Deployment Testing:

# Test Railway deployment
RAILWAY_URL=https://your-app.railway.app npm run test:deployment

# Test health endpoints
curl https://your-app.railway.app/health
curl https://your-app.railway.app/ready

� Integration Guides

Comprehensive step-by-step guides for integrating Aimfox MCP Server with popular platforms:

• - Complete guide for Claude AI (web & desktop) with 20+ example prompts
• - GitHub Copilot integration with developer workflows and chat examples
• - Automation workflows, scenarios, and troubleshooting
• - Lead enrichment, prospecting workflows, and power combinations
• - Workflow automation with AI agents, advanced configuration, and best practices

Each guide includes:

• ✅ Prerequisites and setup instructions
• ✅ Real-world use cases and examples
• ✅ Troubleshooting and common issues
• ✅ Best practices and optimization tips
• ✅ Production-ready configurations

�📄 License

MIT License - see file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Ensure tests pass: npm test
5. Commit your changes: git commit -am 'Add feature'
6. Push to the branch: git push origin feature-name
7. Submit a pull request

📞 Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues

🔗 Related Projects

• Model Context Protocol - Official MCP documentation
• Aimfox - LinkedIn automation platform
• Claude Desktop - AI assistant with MCP support

Built with ❤️ for the Aimfox and MCP community