PlainSignal MCP Server

This is a Model Context Protocol (MCP) server implementation for PlainSignal analytics data. It provides tools for retrieving analytics reports and metrics through the MCP protocol.

Setup

Installation

From npm (recommended)

# Install globally
npm install -g @plainsignal/plainsignal-mcp

# Or install locally in your project
npm install @plainsignal/plainsignal-mcp

From source

Clone this repository
Install dependencies:

npm install

This project uses ES modules instead of CommonJS. Make sure you're using a Node.js version that supports ES modules (Node.js 14+).

Usage

When installed from npm

# If installed globally
plainsignal-mcp --token <your_access_token>

# If installed locally
npx plainsignal-mcp --token <your_access_token>

# Or using an environment variable
export PLAINSIGNAL_TOKEN=<your_access_token>
plainsignal-mcp

When using from source

Run the server with your access token:

node src/index.js --token <your_access_token>

# Or using an environment variable
export PLAINSIGNAL_TOKEN=<your_access_token>
node src/index.js

You can also specify a custom API base URL:

node src/index.js --token <your_access_token> --api-base-url <api_base_url>

Or use the short format:

node src/index.js -t <your_access_token> -u <api_base_url>

Alternatively, set the access token and API base URL as environment variables and use the test script:

export PLAINSIGNAL_TOKEN=your_access_token
export API_BASE_URL=https://app.plainsignal.com/api/v1
./test.sh

By default, the server connects to https://app.plainsignal.com/api/v1.

MCP Server configs

Claude Desktop

Add this snippet to your claude_desktop_config.json:

{
  "mcpServers": {
    "plainsignal": {
      "command": "npx -y @plainsignal/plainsignal-mcp",
      "env": {
        "PLAINSIGNAL_TOKEN": "<YOUR_PLAINSIGNAL_TOKEN>"
      }
    }
  }
}

Available Tools

The server provides the following tools:

getReport

Retrieves an analytics report for a specified domain and time period.

Parameters:

organizationID: Organization ID
domainID: Domain ID
periodFrom: Report start datetime in RFC3339 format
periodTo: Report end datetime in RFC3339 format
periodSelection: Period type (m: month, y: year, d: day)
aggregationWindow: Data aggregation window (h: hour, d: day)
filters: (Optional) List of filters as key-value pairs

getSubReport

Retrieves detailed metrics for a specific aspect of analytics data.

Parameters:

organizationID: Organization ID
domainID: Domain ID
periodFrom: Report start datetime in RFC3339 format
periodTo: Report end datetime in RFC3339 format
periodSelection: Period type (m: month, y: year, d: day)
aggregationWindow: Data aggregation window (h: hour, d: day)
subReportType: Type of report (1: page, 2: entry page, etc.)
filters: (Optional) List of filters as key-values pairs
pagination: (Optional) Pagination controls with limit and offset

API Reference

This server communicates with the PlainSignal API. By default, it connects to https://app.plainsignal.com/api/v1, but you can configure the API endpoint in several ways:

Use the --api-base-url command line option:
node src/index.js --token <your_token> --api-base-url https://app.plainsignal.com/api/v1
Set the API_BASE_URL environment variable:
export API_BASE_URL=https://app.plainsignal.com/api/v1
Pass a custom API base URL to the constructor when instantiating the server programmatically:
const server = new PlainSignalStdioServer(token, 'https://app.plainsignal.com/api/v1');

For Developers

The server is implemented using the MCP SDK and communicates over STDIO.

Examples

An example client is provided to demonstrate how to use the MCP server:

# Set your access token
export PLAINSIGNAL_TOKEN=your_access_token

# Run the example client
npm run example

Or run the resources example client:

# Set your access token
export PLAINSIGNAL_TOKEN=your_access_token

# Run the resources example client
npm run resources-example

The example client demonstrates:

Connecting to the MCP server
Listing available tools
Calling the getReport tool with sample parameters
Processing and displaying the results

The resources example client demonstrates:

Connecting to the MCP server
Listing available resources
Reading the listDomains resource
Processing and displaying the results

License

This project is licensed under the MIT License - see the LICENSE file for details.