plainsignal

PlainSignal MCP Server exposes tools to retrieve analytics reports and metrics from PlainSignal's analytics API via the MCP protocol. The server runs as an MCP-compatible endpoint that you can connect to with an MCP client, listing available tools such as getReport and getSubReport. You configure authentication with your Plainsignal access token, and optionally override the API base URL if you want to connect to a different Plainsignal instance or a staging environment. Typical usage involves starting the server and then invoking the tools to fetch domain- or domain-subset analytics data for specified time ranges. The tools are designed to be invoked through the MCP protocol, returning structured results that you can display or process in your application.

Prerequisites: Node.js 14+ and npm.

1. Install the MCP server from npm (recommended):

   • Globally: npm install -g @plainsignal/plainsignal-mcp
   • Locally in your project: npm install @plainsignal/plainsignal-mcp

2. If you prefer to run from source:

   • Clone the repository
   • Install dependencies: npm install

3. Run the MCP server (from npm):

   • If installed globally: plainsignal-mcp --token <your_access_token>
   • If installed locally (via npx): npx plainsignal-mcp --token <your_access_token>
   • Alternatively, set token via environment variable: export PLAINSIGNAL_TOKEN=<your_access_token> plainsignal-mcp

4. Run from source:

   • node src/index.js --token <your_access_token>
   • Or with environment variable: export PLAINSIGNAL_TOKEN=<your_access_token> node src/index.js

5. Optional: override API base URL if needed using --api-base-url or API_BASE_URL environment variable.

Tips and notes:

• This server uses ES modules; ensure your Node.js version supports ESM (Node.js 14+).
• The server communicates with the Plainsignal API by default against https://app.plainsignal.com/api/v1; you can override this with --api-base-url or the API_BASE_URL env variable.
• To configure authentication securely, prefer passing the token via environment variable PLAINSIGNAL_TOKEN or using the --token flag.
• The MCP client can list available tools, call getReport and getSubReport with the required parameters (organizationID, domainID, periodFrom, periodTo, periodSelection, aggregationWindow, etc.).
• When running from source, you can customize the base URL with node src/index.js --token <token> --api-base-url <url>, or set API_BASE_URL in the environment.
• For debugging, check logs for token errors or API endpoint issues; ensure your token has the necessary permissions for the requested data.