plausible-mcp 0.1.0__tar.gz

plausible_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Surendran B
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plausible_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: plausible-mcp
+Version: 0.1.0
+Summary: Plausible Analytics MCP server: privacy-first website statistics, real-time visitors, breakdowns, and trendlines for AI agents.
+Author-email: Surendran B <reachsuren@gmail.com>
+License-Expression: MIT
+Keywords: mcp,plausible,analytics,stats,agents,fastmcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+Dynamic: license-file
+
+# plausible-mcp
+
+[![PyPI version](https://img.shields.io/pypi/v/plausible-mcp.svg)](https://pypi.org/project/plausible-mcp/)
+[![npm version](https://img.shields.io/npm/v/plausible-analytics-mcp.svg)](https://www.npmjs.com/package/plausible-analytics-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Fast, privacy-first [Plausible Analytics](https://plausible.io) Model Context Protocol (MCP) server for AI coding agents and LLM harnesses. Works seamlessly with both Plausible Cloud and self-hosted Plausible installations.
+
+## Quick Start
+
+### Run with uvx (Python)
+```bash
+export PLAUSIBLE_API_KEY="your_api_key_here"
+uvx plausible-mcp
+```
+
+### Run with npx (Node / npm bridge)
+```bash
+export PLAUSIBLE_API_KEY="your_api_key_here"
+npx -y plausible-analytics-mcp
+```
+
+## Environment Configuration
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `PLAUSIBLE_API_KEY` | Your Plausible Stats/Sites API token | Required (or pass via tool `token` arg) |
+| `PLAUSIBLE_BASE_URL` | Base URL for self-hosted Plausible | `https://plausible.io` |
+| `DO_NOT_TRACK` | Set to `1` to disable anonymous telemetry | `0` |
+
+### Getting an API Key
+1. Log in to Plausible (Cloud or your self-hosted instance).
+2. Go to **Settings** (user profile menu) -> **API Keys**.
+3. Click **+ New Key**, name it `mcp-agent`, and copy the token.
+4. Export as `PLAUSIBLE_API_KEY="your_token"`.
+
+## Available Tools
+
+| Tool | Description |
+| :--- | :--- |
+| `get_aggregate_stats(site_id, date_range="30d", metrics=None, token=None)` | High-level visitor, pageview, bounce rate, and session duration totals |
+| `get_breakdown(site_id, property_name="event:page", date_range="30d", limit=20, token=None)` | Segment metrics by pages, traffic sources, countries, browsers, OS, devices |
+| `get_realtime_visitors(site_id, token=None)` | Current count of active visitors on the site right now |
+| `get_timeseries(site_id, date_range="30d", interval="date", token=None)` | Daily or monthly trendline data points for chart generation |
+| `doctor(token=None)` | Test Plausible API connectivity and validate the configured API token |
+| `skills_list()` | List dynamic analytics playbooks and methodology guides |
+| `skill_read(name)` | Fetch full markdown playbook by name (e.g. `plausible-overview`, `analytics-recipes`) |
+| `check_for_updates()` | Check PyPI for newer versions and view upgrade commands |
+
+## Error Absorption Standard
+
+Errors returned to agents are explicitly classified:
+- `[INPUT_FIXABLE]`: Parameter errors (e.g., misspelled site_id, unknown dimension). Fix arguments and retry.
+- `[ENVIRONMENT_FIXABLE: STOP & ASK HUMAN]`: Missing, expired, or unauthorized API key. Prompt user with guided setup steps.
+- `[TRANSIENT]`: Upstream rate limits (HTTP 429) or network hiccups. Wait briefly and retry.
+
+## MCP Client Setup
+
+### Claude Desktop (`claude_desktop_config.json`)
+```json
+{
+  "mcpServers": {
+    "plausible": {
+      "command": "uvx",
+      "args": ["plausible-mcp"],
+      "env": {
+        "PLAUSIBLE_API_KEY": "YOUR_PLAUSIBLE_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Or using the npm bridge:
+```json
+{
+  "mcpServers": {
+    "plausible": {
+      "command": "npx",
+      "args": ["-y", "plausible-analytics-mcp"],
+      "env": {
+        "PLAUSIBLE_API_KEY": "YOUR_PLAUSIBLE_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

plausible_mcp-0.1.0/README.md

@@ -0,0 +1,91 @@
+# plausible-mcp
+
+[![PyPI version](https://img.shields.io/pypi/v/plausible-mcp.svg)](https://pypi.org/project/plausible-mcp/)
+[![npm version](https://img.shields.io/npm/v/plausible-analytics-mcp.svg)](https://www.npmjs.com/package/plausible-analytics-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Fast, privacy-first [Plausible Analytics](https://plausible.io) Model Context Protocol (MCP) server for AI coding agents and LLM harnesses. Works seamlessly with both Plausible Cloud and self-hosted Plausible installations.
+
+## Quick Start
+
+### Run with uvx (Python)
+```bash
+export PLAUSIBLE_API_KEY="your_api_key_here"
+uvx plausible-mcp
+```
+
+### Run with npx (Node / npm bridge)
+```bash
+export PLAUSIBLE_API_KEY="your_api_key_here"
+npx -y plausible-analytics-mcp
+```
+
+## Environment Configuration
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `PLAUSIBLE_API_KEY` | Your Plausible Stats/Sites API token | Required (or pass via tool `token` arg) |
+| `PLAUSIBLE_BASE_URL` | Base URL for self-hosted Plausible | `https://plausible.io` |
+| `DO_NOT_TRACK` | Set to `1` to disable anonymous telemetry | `0` |
+
+### Getting an API Key
+1. Log in to Plausible (Cloud or your self-hosted instance).
+2. Go to **Settings** (user profile menu) -> **API Keys**.
+3. Click **+ New Key**, name it `mcp-agent`, and copy the token.
+4. Export as `PLAUSIBLE_API_KEY="your_token"`.
+
+## Available Tools
+
+| Tool | Description |
+| :--- | :--- |
+| `get_aggregate_stats(site_id, date_range="30d", metrics=None, token=None)` | High-level visitor, pageview, bounce rate, and session duration totals |
+| `get_breakdown(site_id, property_name="event:page", date_range="30d", limit=20, token=None)` | Segment metrics by pages, traffic sources, countries, browsers, OS, devices |
+| `get_realtime_visitors(site_id, token=None)` | Current count of active visitors on the site right now |
+| `get_timeseries(site_id, date_range="30d", interval="date", token=None)` | Daily or monthly trendline data points for chart generation |
+| `doctor(token=None)` | Test Plausible API connectivity and validate the configured API token |
+| `skills_list()` | List dynamic analytics playbooks and methodology guides |
+| `skill_read(name)` | Fetch full markdown playbook by name (e.g. `plausible-overview`, `analytics-recipes`) |
+| `check_for_updates()` | Check PyPI for newer versions and view upgrade commands |
+
+## Error Absorption Standard
+
+Errors returned to agents are explicitly classified:
+- `[INPUT_FIXABLE]`: Parameter errors (e.g., misspelled site_id, unknown dimension). Fix arguments and retry.
+- `[ENVIRONMENT_FIXABLE: STOP & ASK HUMAN]`: Missing, expired, or unauthorized API key. Prompt user with guided setup steps.
+- `[TRANSIENT]`: Upstream rate limits (HTTP 429) or network hiccups. Wait briefly and retry.
+
+## MCP Client Setup
+
+### Claude Desktop (`claude_desktop_config.json`)
+```json
+{
+  "mcpServers": {
+    "plausible": {
+      "command": "uvx",
+      "args": ["plausible-mcp"],
+      "env": {
+        "PLAUSIBLE_API_KEY": "YOUR_PLAUSIBLE_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Or using the npm bridge:
+```json
+{
+  "mcpServers": {
+    "plausible": {
+      "command": "npx",
+      "args": ["-y", "plausible-analytics-mcp"],
+      "env": {
+        "PLAUSIBLE_API_KEY": "YOUR_PLAUSIBLE_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

plausible_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "plausible-mcp"
+version = "0.1.0"
+description = "Plausible Analytics MCP server: privacy-first website statistics, real-time visitors, breakdowns, and trendlines for AI agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Surendran B", email = "reachsuren@gmail.com" }]
+keywords = ["mcp", "plausible", "analytics", "stats", "agents", "fastmcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=1.2.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[project.scripts]
+plausible-mcp = "plausible_mcp.server:main"
+plausible-analytics-mcp = "plausible_mcp.server:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+plausible_mcp = ["skills/*.md", "py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

plausible_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

plausible_mcp-0.1.0/src/plausible_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Plausible Analytics MCP server for AI agents."""
+
+__version__ = "0.1.0"