matomo-js

This MCP server provides a bridge between AI agents and Matomo Analytics by exposing selected Matomo Reporting API modules as MCP tools. Currently, the implementation includes four modules: SitesManager, TagManager, Tour, and UserId. Agents can invoke these tools to interact with Matomo data programmatically, such as retrieving site configurations, managing tags, accessing guided tour data, or tracing user identifiers. The server adheres to the MCP specification, allowing clients to discover available tools, call endpoints with structured parameters, and receive typed responses. To start using it, configure the required environment variables (e.g., Matomo base URL and authentication) and run the server. Once running, you can query the available tools and pass in the appropriate parameters to perform common Matomo tasks without directly handling API requests.

Prerequisites:

• Node.js v18+ installed
• npm, yarn, or pnpm

1. Install the MCP server package (and its dependencies)
   • npm install @mj-kiwi/matomo-mcp-server
   • or yarn add @mj-kiwi/matomo-mcp-server
   • or pnpm add @mj-kiwi/matomo-mcp-server

2)Configure environment variables (examples below)

• Create a .env file or export variables in your runtime environment: MATOMO_BASE_URL=https://your-matomo-instance.com MATOMO_TOKEN_AUTH=your-token-if-needed MATOMO_SITE_ID=default-site-id MCP_PORT=3000

3. Run the MCP server

   • node path/to/server.js
   • Or use a process manager to keep it running (e.g., PM2, systemd)

4. (Optional) Verify installation

   • Send a test MCP request to the server endpoint to list available tools and perform a basic query against the SitesManager or UserId tools.

Prerequisites recap:

• Node.js v18+ and a package manager
• Access to a Matomo instance with appropriate credentials
• Basic knowledge of MCP tool invocation syntax

Tips:

• Only four Matomo modules are implemented in this MCP server at the moment (SitesManager, TagManager, Tour, UserId). Additional modules may be added over time.
• Ensure your Matomo instance is reachable from the host running the MCP server and that authentication (if required) is correctly configured via environment variables.
• If your Matomo instance uses token authentication, set MATOMO_TOKEN_AUTH accordingly; omit or leave empty if not used.
• Consider using a process manager for production deployments to handle restarts and logging.
• Use explicit, typed input parameters for tool calls to reduce ambiguity and improve reliability.

Environment variables:

• MATOMO_BASE_URL: Base URL for your Matomo instance
• MATOMO_TOKEN_AUTH: Optional token for authentication
• MATOMO_SITE_ID: Default site ID to query if not specified per request
• MCP_PORT: Port on which the MCP server listens