Moz STAT Analytics MCP Server

This is a Model Context Protocol (MCP) server designed to interact with the Moz STAT Keyword Analytics API. It provides a programmatic interface for accessing various Moz STAT data endpoints, enabling integration with other tools and automation workflows.

NOTE: The server uses StdioServerTransport for both production and local testing, as expected by the MCP specification. This ensures that the local development environment closely mirrors the production setup.

Table of Contents

• Features
• Local Development & Testing
• Configuration
• Deployment to Google Cloud Run
• Usage (MCP Integration)
• Contributing
• License

Features

• Connects to the Moz STAT API for keyword analytics.
• Implements a wide range of non-optional STAT API endpoints.
• Uses Zod for robust input validation of all API requests.
• Securely handles the STAT API key via environment variables.
• Built using TypeScript for better code quality and maintainability.
• Containerized with Docker for easy deployment.

Local Development & Testing

Setup

First, set up the project and install dependencies:

# Clone the repository
git clone https://github.com/bdmarvin1/mcp-server-stat-analytics.git
cd mcp-server-stat-analytics

# Install dependencies
npm install

# Create a .env file in the root directory and add your API key and subdomain.
# You can copy the example file to get started:
# cp .env.example .env
#
# Then, edit .env with your actual credentials:
# STAT_API_KEY="YOUR_MOZ_STAT_API_KEY"
# STAT_SUBDOMAIN="YOUR_MOZ_STAT_SUBDOMAIN" # e.g., golocal

Due to issues with the stdio transport in some local environments, a reliable local test is not currently available. The server should be tested in its target deployment environment.

Configuration

Moz STAT API Key & Subdomain

The Moz STAT API requires both a STAT_API_KEY and a STAT_SUBDOMAIN (e.g., golocal) to construct the correct API endpoint. Both must be provided as environment variables.

• Local Development: Set them in a .env file as described in the Setup section.
• Google Cloud Run Deployment: Configure STAT_API_KEY and STAT_SUBDOMAIN as environment variables when deploying your service.

Deployment to Google Cloud Run

The Dockerfile is configured to use the standard StdioServerTransport when run in a production environment.

1. Build the Docker image:

   docker build -t gcr.io/[YOUR_GCP_PROJECT_ID]/mcp-server-stat-analytics:latest .

   Replace [YOUR_GCP_PROJECT_ID] with your Google Cloud Project ID.

2. Push the Docker image to Google Container Registry (GCR):

   docker push gcr.io/[YOUR_GCP_PROJECT_ID]/mcp-server-stat-analytics:latest

3. Deploy to Google Cloud Run:

   gcloud run deploy mcp-server-stat-analytics \
     --image gcr.io/[YOUR_GCP_PROJECT_ID]/mcp-server-stat-analytics:latest \
     --platform managed \
     --region [YOUR_GCP_REGION] \
     --allow-unauthenticated \
     --set-env-vars STAT_API_KEY=YOUR_MOZ_STAT_API_KEY,STAT_SUBDOMAIN=YOUR_MOZ_STAT_SUBDOMAIN

   • Replace [YOUR_GCP_PROJECT_ID] and [YOUR_GCP_REGION].
   • Crucially, replace YOUR_MOZ_STAT_API_KEY and YOUR_MOZ_STAT_SUBDOMAIN with your actual values.

Usage (MCP Integration)

Once deployed, the MCP controller will spawn this server and communicate with it over stdio, as intended by the protocol. The server will expose all stat_* tools for use.

Contributing

Contributions are welcome! Please feel free to open issues or submit pull requests.

License

This project is licensed under the MIT License.