MCP Server

Prerequisites & Pricing

The MCP Server uses the Fanpage Karma Data API v2. To use it, you need an active API subscription (included in Gold plans and above).

Use the list_queried_profiles tool to check which profiles have been queried in the current billing period. See Settings → API for your current usage.

Authentication

The MCP Server supports two authentication methods. Choose the one that fits your client:

Bearer Token

For desktop apps, CLI tools, and automation platforms. You configure a static API token in the client.

The token is sent as Authorization: Bearer YOUR_TOKEN header with every request. See the setup guides below for client-specific configuration.

OAuth 2.1

For browser-based clients that support the OAuth 2.1 standard (e.g. Claude Web). No API token is needed — you authorize access by logging in to your Fanpage Karma account.

The client handles the OAuth flow automatically (dynamic client registration, PKCE, token refresh). See Browser-based Clients (OAuth) for details.

Compatibility

The MCP Server works with any client that supports the MCP standard. Depending on the client, authentication is done via Bearer Token or OAuth 2.1.

Client	Auth Method	Notes
Claude Desktop	Bearer Token	Via claude_desktop_config.json
Claude Code (CLI)	Bearer Token	Via claude mcp add or .mcp.json
Cursor / Windsurf	Bearer Token	Custom header configuration
n8n	Bearer Token	MCP Client Tool node
ChatGPT Desktop	Bearer Token	Custom header configuration
Claude Web (claude.ai)	OAuth 2.1	Add as Connector in Settings → Connectors
Other browser-based clients	OAuth 2.1	Any MCP client supporting OAuth 2.1 with PKCE

Setup: Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Copy{
"mcpServers": {
"fanpagekarma": {
"url": "https://app.fanpagekarma.com/api/v2/mcp",
"headers": {
"Authorization": "Bearer your-api-token-here"
}
}
}
}

Restart Claude Desktop after saving the file.

Setup: Claude Code

Run the following command in your terminal:

Copyclaude mcp add --transport http fanpagekarma https://app.fanpagekarma.com/api/v2/mcp \
--header "Authorization: Bearer your-api-token-here"

Or add to your project's .mcp.json:

Copy{
"mcpServers": {
"fanpagekarma": {
"type": "http",
"url": "https://app.fanpagekarma.com/api/v2/mcp",
"headers": {
"Authorization": "Bearer your-api-token-here"
}
}
}
}

Setup: n8n

Use the MCP Client Tool node with the hosted service:

Browser-based Clients (OAuth)

MCP clients that run in the browser can connect via OAuth 2.1 instead of a static API token. You authorize access by logging in to your Fanpage Karma account — no token copy-paste needed.

The general setup for any OAuth-capable MCP client:

Example: Claude Web (claude.ai)

In claude.ai, go to Settings → Connectors, click Add Custom Connector, and enter the server URL above. Claude handles the rest automatically.

Other Clients

Any MCP-compatible client (Cursor, Windsurf, ChatGPT, custom integrations, etc.) can connect using the HTTP endpoints below. See Authentication for how to authenticate.

Bearer Token Header

For clients using Bearer Token authentication, include the token in every request:

CopyAuthorization: Bearer your-api-token-here

Endpoints

Method	Endpoint	Description
POST	/api/v2/mcp	Send messages (Streamable HTTP)
GET	/api/v2/mcp	SSE stream (requires mcp-session-id header)
DELETE	/api/v2/mcp	Close session
GET	/api/v2/mcp/sse	Establish SSE connection (legacy)
POST	/api/v2/mcp/messages	Send messages via SSE (legacy)

Most clients support Streamable HTTP. Use the SSE endpoints only if your client requires the legacy SSE transport.

Available Tools

The MCP server exposes seven tools that map to the API v2 endpoints:

Tool	Description	Parameters
list_connected_profiles	List your connected social media profiles with extended analytics	—
list_queried_profiles	List profiles queried via API in current billing period	—
list_available_metrics	List available metric keys, labels and types for a network and endpoint	networkrequired, endpointrequired
get_profile_metrics	Get profile-level metrics (followers, engagement, reach, etc.)	networkrequired, profile_idrequired, from, to, metrics
get_profile_posts	Get posts with engagement metrics	networkrequired, profile_idrequired, from, to, limit, offset
get_profile_stories	Get Instagram Stories data	profile_idrequired, from, to, limit, offset
get_profile_daily	Get daily time series for specific metrics	networkrequired, profile_idrequired, metricsrequired, from, to

Date parameters use YYYY-MM-DD format. If omitted, the last 28 days are used.
Use list_available_metrics or GET /api/v2/{network}/{endpoint}/metrics to discover available metric keys.
The get_profile_daily tool uses the /profile/daily endpoint path.

Supported Networks

The following networks are available for all profile tools:

• facebook
• instagram
• youtube
• linkedin
• tiktok
• threads
• bluesky
• pinterest

The get_profile_stories tool is only available for Instagram.

Usage Examples

Once configured, you can ask your AI assistant questions like: