README.md•4.07 kB
# Zocialeye MCP Server
A simple remote MCP server for Zocialeye social media analytics API.
## Quick Start
```bash
# Install
npm install
npm run build
# Run
npm start
```
Server runs on `http://localhost:3000` (configurable via `PORT` env var).
## Configuration
### Claude Desktop Setup
Edit your Claude Desktop config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"zocialeye": {
"type": "streamable-http",
"url": "http://localhost:3000/12345/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
Replace:
- `12345` with your numeric campaign ID
- `YOUR_API_KEY` with your Zocialeye API key
## Authentication
The server uses URL-based campaign ID + custom header authentication with Streamable HTTP transport:
1. **Campaign ID**: In URL path (must be numeric)
- Format: `http://localhost:3000/{campaign_id}/mcp`
- Example: `http://localhost:3000/12345/mcp`
2. **API Key**: In Authorization header (Bearer token)
- Format: `Authorization: Bearer <your-api-key>`
3. **Transport**: Streamable HTTP (POST requests)
## Available Tools
1. **get_campaign_wordcloud** - Word cloud data with sentiment analysis
2. **get_campaign_messages** - Messages/posts with filtering and pagination
3. **get_campaign_summary** - Time-series statistics (hourly/daily)
4. **get_campaign_influencers** - Top influencers and engagement metrics
5. **get_campaign_categories** - Available categories for the campaign
6. **get_campaign_keywords** - Tracked keywords for the campaign
All tools support:
- Date range filtering (ISO 8601 format)
- Group by (category, sentiment, keywords, etc.)
- Channel filtering (Facebook, X, Instagram, TikTok, etc.)
- Sentiment filtering (positive, negative, neutral)
## Testing
```bash
# Health check (no auth required)
curl http://localhost:3000/health
# MCP endpoint (requires auth) - List tools
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
http://localhost:3000/12345/mcp
```
### Testing with MCP Inspector
Using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
```bash
# Start Inspector
npx @modelcontextprotocol/inspector
# Or use CLI mode
npx @modelcontextprotocol/inspector --cli \
http://localhost:3000/12345/mcp \
--transport streamable-http \
--header "Authorization: Bearer YOUR_API_KEY" \
--method tools/list
```
In the Inspector UI:
1. Set **Transport**: `Streamable HTTP`
2. Set **URL**: `http://localhost:3000/12345/mcp`
3. Set **Token** (Authorization header): `YOUR_API_KEY` (Inspector will add "Bearer " prefix)
4. Click **Connect**
## Deployment
### Docker
```bash
docker build -t zocialeye-mcp .
docker run -d -p 3000:3000 zocialeye-mcp
```
Or use docker-compose:
```bash
docker-compose up -d
```
### Cloud Platforms
Deploy to Heroku, Railway, Render, Fly.io, etc. No environment variables needed - clients provide credentials via headers.
Then update your Claude Desktop config with the deployed URL:
```json
{
"type": "streamable-http",
"url": "https://your-server.com/12345/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
```
## Environment Variables
Optional server configuration:
- `PORT` - Server port (default: 3000)
- `ZOCIALEYE_API_URL` - Custom API URL (default: https://apix.zocialeye.com/api/v1)
## Troubleshooting
**401 Unauthorized**
- Verify campaign ID is numeric (digits only)
- Check Authorization header is present with Bearer prefix
- Ensure API key is valid
**Connection Refused**
- Check server is running
- Verify URL and port
**No Data**
- Confirm campaign ID is correct
- Verify API key has access to the campaign
## Architecture
Simple single-file design:
- One file: `src/index.ts` (~290 lines)
- No complex abstractions
- Easy to understand and modify
- All tools in one place
## License
MIT