TROUBLESHOOTING.md•6.87 kB
# Troubleshooting Guide
## Common Issues and Solutions
### 1. Server Not Appearing in Claude Desktop
**Problem**: The Apollo MCP server doesn't show up in Claude Desktop's available tools.
**Solutions**:
#### Check Configuration File Location
Verify you're editing the correct config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
#### Verify Configuration Format
Your config should look like this:
```json
{
"mcpServers": {
"apollo": {
"command": "node",
"args": [
"/absolute/path/to/apollo.io-mcp/build/index.js"
],
"env": {
"APOLLO_API_KEY": "your_actual_api_key_here"
}
}
}
}
```
**Important**:
- Use the **absolute path** (not relative)
- Replace `/absolute/path/to/apollo.io-mcp` with your actual path
- Replace `your_actual_api_key_here` with your real Apollo.io API key
#### Get the Absolute Path
```bash
# macOS/Linux
cd /path/to/apollo.io-mcp
pwd
# This will show the absolute path like: /Users/yourname/projects/apollo.io-mcp
# Windows (PowerShell)
cd \path\to\apollo.io-mcp
(Get-Location).Path
```
#### Verify Build
Make sure the server is built:
```bash
cd /path/to/apollo.io-mcp
npm run build
```
#### Check File Permissions (macOS/Linux)
```bash
chmod +x /path/to/apollo.io-mcp/build/index.js
```
#### Restart Claude Desktop
After updating the config, **completely quit and restart** Claude Desktop (not just close the window).
### 2. "APOLLO_API_KEY environment variable is required" Error
**Problem**: Server exits immediately with API key error.
**Solution**: Make sure your API key is set in the `claude_desktop_config.json`:
```json
{
"mcpServers": {
"apollo": {
"command": "node",
"args": ["/absolute/path/to/apollo.io-mcp/build/index.js"],
"env": {
"APOLLO_API_KEY": "your_apollo_api_key_here"
}
}
}
}
```
**Get Your API Key**:
1. Log in to Apollo.io
2. Go to Settings → Integrations → API
3. Copy your API key
4. Paste it in the config (without quotes inside the value)
### 3. Server Starts But Tools Don't Work
**Problem**: Server appears in Claude but API calls fail.
**Possible Causes**:
#### Invalid API Key
- Verify your API key is correct
- Check it hasn't been revoked
- Ensure it has the necessary permissions
#### API Rate Limits
- Check your Apollo.io plan limits
- View usage at: https://app.apollo.io/#/settings/integrations/api
- Free plan: 50 credits/month
- Paid plans: Much higher limits
#### Network Issues
- Ensure your computer can reach api.apollo.io
- Check firewall settings
- Test: `curl https://api.apollo.io/v1/auth/health -H "X-Api-Key: your_key"`
### 4. Module Not Found Errors
**Problem**: Error about missing modules.
**Solution**:
```bash
cd /path/to/apollo.io-mcp
rm -rf node_modules package-lock.json
npm install
npm run build
```
### 5. TypeScript Compilation Errors
**Problem**: Build fails with TypeScript errors.
**Solution**:
```bash
# Update dependencies
npm install
# Clean build
rm -rf build/
npm run build
```
### 6. Checking Logs
#### macOS
```bash
# Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp*.log
# System logs
log show --predicate 'process == "Claude"' --last 5m
```
#### Windows
Check: `%APPDATA%\Claude\logs\`
### 7. Testing the Server Manually
Test if the server starts:
```bash
cd /path/to/apollo.io-mcp
export APOLLO_API_KEY="your_key_here" # macOS/Linux
# or
$env:APOLLO_API_KEY="your_key_here" # Windows PowerShell
npm run build
node build/index.js
```
You should see: `Apollo.io MCP Server running on stdio`
Press Ctrl+C to exit.
### 8. Verify Installation
Run this checklist:
```bash
# 1. Check Node.js version (should be 18+)
node --version
# 2. Navigate to project
cd /path/to/apollo.io-mcp
# 3. Verify files exist
ls -la build/index.js
ls -la package.json
# 4. Check dependencies
npm list --depth=0
# 5. Rebuild
npm run build
# 6. Test run (with your API key)
export APOLLO_API_KEY="your_key"
timeout 2 node build/index.js
```
### 9. Common Configuration Mistakes
❌ **Wrong - Relative Path**:
```json
{
"mcpServers": {
"apollo": {
"command": "node",
"args": ["./build/index.js"] // Wrong!
}
}
}
```
✅ **Correct - Absolute Path**:
```json
{
"mcpServers": {
"apollo": {
"command": "node",
"args": ["/Users/yourname/projects/apollo.io-mcp/build/index.js"]
}
}
}
```
❌ **Wrong - Missing API Key**:
```json
{
"mcpServers": {
"apollo": {
"command": "node",
"args": ["/path/to/apollo.io-mcp/build/index.js"]
// Missing env!
}
}
}
```
✅ **Correct - With API Key**:
```json
{
"mcpServers": {
"apollo": {
"command": "node",
"args": ["/path/to/apollo.io-mcp/build/index.js"],
"env": {
"APOLLO_API_KEY": "your_key_here"
}
}
}
}
```
### 10. Still Not Working?
1. **Check Claude Desktop Version**: Update to the latest version
2. **Check Node.js Version**: Should be 18 or higher (`node --version`)
3. **Review MCP Documentation**: https://modelcontextprotocol.io/
4. **Check Apollo API Status**: https://status.apollo.io/
5. **Test API Key Manually**:
```bash
curl -X POST https://api.apollo.io/v1/auth/health \
-H "Content-Type: application/json" \
-H "X-Api-Key: your_api_key_here"
```
### Debug Mode
To see detailed server logs:
1. Modify `src/index.ts` to add logging:
```typescript
// At the top of setupHandlers()
this.server.onerror = (error) => {
console.error("[MCP Error]", error);
};
// In CallToolRequestSchema handler
console.error(`[MCP] Calling tool: ${name}`);
console.error(`[MCP] With args:`, JSON.stringify(args));
```
2. Rebuild:
```bash
npm run build
```
3. Check logs in Claude Desktop's log directory
## Getting Help
If you're still having issues:
1. **Gather Information**:
- Node.js version: `node --version`
- NPM version: `npm --version`
- Operating system
- Claude Desktop version
- Full error message
- Contents of your config file (remove API key)
2. **Check**:
- Can you run `node build/index.js` manually?
- Does `npm run build` complete without errors?
- Is your API key valid?
3. **Common Quick Fixes**:
```bash
# Complete reset
cd /path/to/apollo.io-mcp
rm -rf node_modules build package-lock.json
npm install
npm run build
chmod +x build/index.js
# Then restart Claude Desktop
```
## Verification Checklist
- [ ] Node.js 18+ installed
- [ ] Project built (`npm run build` succeeded)
- [ ] `build/index.js` exists and is executable
- [ ] Apollo.io API key obtained
- [ ] `claude_desktop_config.json` updated with absolute path
- [ ] API key added to config
- [ ] Claude Desktop restarted
- [ ] No syntax errors in config JSON
- [ ] Correct config file location for your OS