Clicky MCP Server

A Model Context Protocol (MCP) server for fetching traffic analytics data from the Clicky API.

Features

This MCP server provides five tools to interact with Clicky analytics:

get_total_visitors - Get total visitors for a date range
get_domain_visitors - Get visitors filtered by referrer domain
get_top_pages - Get top pages for a date range
get_traffic_sources - Get traffic sources breakdown for a date range
get_page_traffic - Get traffic data for a specific page by URL

Setup

Install dependencies:

npm install

Build the project:

npm run build

Run the server:

npm start

Or for development:

npm run dev

Configuration

You need to provide your Clicky analytics credentials to use this server. Get these from your Clicky account:

Get your credentials from your Clicky account:
- Site ID: Available in your site preferences
- Site Key: Available in your site preferences under "Preferences" → "Info"

Configure credentials using one of these methods:

Option 1: Environment variables

export CLICKY_SITE_ID="YOUR_SITE_ID"
export CLICKY_SITE_KEY="YOUR_SITE_KEY"

Option 2: Command line arguments

npm start -- --site-id YOUR_SITE_ID --site-key YOUR_SITE_KEY

Option 3: .env file

# Create .env file in project root
CLICKY_SITE_ID=YOUR_SITE_ID
CLICKY_SITE_KEY=YOUR_SITE_KEY

⚠️ Security Note: Never commit your actual credentials to version control. The .env file is already included in .gitignore for security.

Using with Claude Desktop

To use this MCP server with Claude Desktop, you need to add it to your Claude Desktop configuration:

Locate your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

Add the MCP server to your config:

{
  "mcpServers": {
    "clicky-analytics": {
      "command": "node",
      "args": ["/path/to/clicky-mcp/dist/index.js"],
      "env": {
        "CLICKY_SITE_ID": "YOUR_SITE_ID",
        "CLICKY_SITE_KEY": "YOUR_SITE_KEY"
      }
    }
  }
}

Update the path: Replace /path/to/clicky-mcp/ with the actual path to your cloned repository.
Add your credentials: Replace YOUR_SITE_ID and YOUR_SITE_KEY with your actual Clicky credentials.
Restart Claude Desktop for the changes to take effect.

Once configured, you'll be able to use tools like "get traffic sources for my website" or "show me top pages from last week" directly in Claude Desktop conversations.

Available Tools

get_total_visitors

Get total visitor counts for a specified date range.

Parameters:

start_date (string, required): Start date in YYYY-MM-DD format
end_date (string, required): End date in YYYY-MM-DD format

Example:

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

get_domain_visitors

Get visitor data filtered by referrer domain with optional segmentation data.

Parameters:

domain (string, required): Domain name to filter by (e.g., "facebook.com", "google.com")
start_date (string, required): Start date in YYYY-MM-DD format
end_date (string, required): End date in YYYY-MM-DD format
segments (array, optional): Array of segments to include. Options: "pages", "visitors". Defaults to "visitors" only.
- "visitors": Gets the total number of visitors from the domain
- "pages": Gets the list of pages and their visit counts from the domain
limit (number, optional): Maximum number of results to return (1-1000)

Basic Example (visitor count only):

{
  "domain": "facebook.com",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

Advanced Example (with segmentation):

{
  "domain": "facebook.com",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "segments": ["pages", "visitors"],
  "limit": 100
}

get_top_pages

Get the most popular pages for a date range.

Parameters:

start_date (string, required): Start date in YYYY-MM-DD format
end_date (string, required): End date in YYYY-MM-DD format
limit (number, optional): Maximum number of pages to return (1-1000)

Example:

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "limit": 50
}

get_traffic_sources

Get traffic sources breakdown showing where visitors come from. Optionally filter by specific page URL.

Parameters:

start_date (string, required): Start date in YYYY-MM-DD format
end_date (string, required): End date in YYYY-MM-DD format
page_url (string, optional): Full URL or path of the page to get traffic sources for (e.g., "https://example.com/path" or "/path")

Example:

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

Example with page filter:

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "page_url": "https://example.com/blog/post"
}

Returns: Clean breakdown of traffic sources with visitor counts and percentages for sources like Direct, Search engines, Social media, Links, etc.

get_page_traffic

Get traffic data for a specific page by filtering with its URL.

Parameters:

url (string, required): Full URL or path of the page (e.g., "https://example.com/page" or "/page")
start_date (string, required): Start date in YYYY-MM-DD format
end_date (string, required): End date in YYYY-MM-DD format

Example:

{
  "url": "https://news.ycombinator.com/show",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

Returns: Traffic data for the specific page including visitor counts, actions, and other page-specific metrics.

API Limitations

Maximum date range: 31 days (enforced by Clicky API)
Maximum results per request: 1,000 items
One simultaneous request per IP address per site ID

Error Handling

The server includes built-in error handling for:

Invalid date ranges (> 31 days)
API rate limits
Network errors
Invalid parameters

All errors are returned with descriptive messages to help with debugging.

Development

The project structure:

clicky-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── clicky-client.ts      # Clicky API client
│   └── tools/
│       ├── get-total-visitors.ts
│       ├── get-domain-visitors.ts
│       ├── get-top-pages.ts
│       ├── get-traffic-sources.ts
│       └── get-page-traffic.ts
├── package.json
├── tsconfig.json
└── README.md

License

MIT

Clicky MCP Server

A Model Context Protocol (MCP) server for fetching traffic analytics data from the Clicky API.

Features

This MCP server provides five tools to interact with Clicky analytics:

get_total_visitors - Get total visitors for a date range
get_domain_visitors - Get visitors filtered by referrer domain
get_top_pages - Get top pages for a date range
get_traffic_sources - Get traffic sources breakdown for a date range
get_page_traffic - Get traffic data for a specific page by URL

Setup

Install dependencies:

npm install

Build the project:

npm run build

Run the server:

npm start

Or for development:

npm run dev

Configuration

You need to provide your Clicky analytics credentials to use this server. Get these from your Clicky account:

Get your credentials from your Clicky account:
- Site ID: Available in your site preferences
- Site Key: Available in your site preferences under "Preferences" → "Info"

Configure credentials using one of these methods:

Option 1: Environment variables

export CLICKY_SITE_ID="YOUR_SITE_ID"
export CLICKY_SITE_KEY="YOUR_SITE_KEY"

Option 2: Command line arguments

npm start -- --site-id YOUR_SITE_ID --site-key YOUR_SITE_KEY

Option 3: .env file

# Create .env file in project root
CLICKY_SITE_ID=YOUR_SITE_ID
CLICKY_SITE_KEY=YOUR_SITE_KEY

⚠️ Security Note: Never commit your actual credentials to version control. The .env file is already included in .gitignore for security.

Using with Claude Desktop

To use this MCP server with Claude Desktop, you need to add it to your Claude Desktop configuration:

Locate your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

Add the MCP server to your config:

{
  "mcpServers": {
    "clicky-analytics": {
      "command": "node",
      "args": ["/path/to/clicky-mcp/dist/index.js"],
      "env": {
        "CLICKY_SITE_ID": "YOUR_SITE_ID",
        "CLICKY_SITE_KEY": "YOUR_SITE_KEY"
      }
    }
  }
}

Update the path: Replace /path/to/clicky-mcp/ with the actual path to your cloned repository.
Add your credentials: Replace YOUR_SITE_ID and YOUR_SITE_KEY with your actual Clicky credentials.
Restart Claude Desktop for the changes to take effect.

Once configured, you'll be able to use tools like "get traffic sources for my website" or "show me top pages from last week" directly in Claude Desktop conversations.

Available Tools

get_total_visitors

Get total visitor counts for a specified date range.

Parameters:

start_date (string, required): Start date in YYYY-MM-DD format
end_date (string, required): End date in YYYY-MM-DD format

Example:

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

get_domain_visitors

Get visitor data filtered by referrer domain with optional segmentation data.

Parameters:

domain (string, required): Domain name to filter by (e.g., "facebook.com", "google.com")
start_date (string, required): Start date in YYYY-MM-DD format
end_date (string, required): End date in YYYY-MM-DD format
segments (array, optional): Array of segments to include. Options: "pages", "visitors". Defaults to "visitors" only.
- "visitors": Gets the total number of visitors from the domain
- "pages": Gets the list of pages and their visit counts from the domain
limit (number, optional): Maximum number of results to return (1-1000)

Basic Example (visitor count only):

{
  "domain": "facebook.com",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

Advanced Example (with segmentation):

{
  "domain": "facebook.com",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "segments": ["pages", "visitors"],
  "limit": 100
}

get_top_pages

Get the most popular pages for a date range.

Parameters:

start_date (string, required): Start date in YYYY-MM-DD format
end_date (string, required): End date in YYYY-MM-DD format
limit (number, optional): Maximum number of pages to return (1-1000)

Example:

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "limit": 50
}

get_traffic_sources

Get traffic sources breakdown showing where visitors come from. Optionally filter by specific page URL.

Parameters:

start_date (string, required): Start date in YYYY-MM-DD format
end_date (string, required): End date in YYYY-MM-DD format
page_url (string, optional): Full URL or path of the page to get traffic sources for (e.g., "https://example.com/path" or "/path")

Example:

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

Example with page filter:

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "page_url": "https://example.com/blog/post"
}

Returns: Clean breakdown of traffic sources with visitor counts and percentages for sources like Direct, Search engines, Social media, Links, etc.

get_page_traffic

Get traffic data for a specific page by filtering with its URL.

Parameters:

url (string, required): Full URL or path of the page (e.g., "https://example.com/page" or "/page")
start_date (string, required): Start date in YYYY-MM-DD format
end_date (string, required): End date in YYYY-MM-DD format

Example:

{
  "url": "https://news.ycombinator.com/show",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

Returns: Traffic data for the specific page including visitor counts, actions, and other page-specific metrics.

API Limitations

Maximum date range: 31 days (enforced by Clicky API)
Maximum results per request: 1,000 items
One simultaneous request per IP address per site ID

Error Handling

The server includes built-in error handling for:

Invalid date ranges (> 31 days)
API rate limits
Network errors
Invalid parameters

All errors are returned with descriptive messages to help with debugging.

Development

The project structure:

clicky-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── clicky-client.ts      # Clicky API client
│   └── tools/
│       ├── get-total-visitors.ts
│       ├── get-domain-visitors.ts
│       ├── get-top-pages.ts
│       ├── get-traffic-sources.ts
│       └── get-page-traffic.ts
├── package.json
├── tsconfig.json
└── README.md

License

MIT