Simple Commenter MCP Server

MCP server that lets AI coding agents (Claude Code, Cursor, etc.) fetch website feedback from Simple Commenter, understand what needs fixing, and update comment status as they work.

Prerequisites

Before using the MCP server, you need a Simple Commenter account with at least one project configured:

1. Sign up at simplecommenter.com
2. Create a project in the dashboard and add your website domain
3. Install the widget on your site (script tag or browser extension)

The MCP server connects to projects you've already set up in the dashboard — it does not create projects for you.

Quick Start

npx @simple-commenter/mcp-server init

The setup wizard will:

1. Authenticate with your email + a 6-digit code
2. Let you pick a default project
3. Configure status preferences for AI workflows
4. Auto-create a .mcp.json in your project root

Restart your AI tool and the MCP server is connected.

Note: npm install only downloads the package — it does not touch .mcp.json. The .mcp.json entry is written by init (it doesn't know which project folder to register otherwise). If you registered the server in a global config (e.g. ~/.claude.json) instead, an empty or missing project .mcp.json is expected and doctor will only show it as a warning.

Verify your setup

npx @simple-commenter/mcp-server doctor

Checks Node.js version, config, and API connectivity (hard checks), and notes the .mcp.json state as a warning if the server isn't registered in the project file.

Available Tools

| Tool | Description | |------|-------------| | list_projects | List all websites/projects in your account | | list_comments | List comments with filters (status, priority, page, search) | | get_comment | Full detail — DOM element XPath, screenshot, click position, replies | | update_comment_status | Mark as in_progress, done, etc. | | reply_to_comment | Reply with what you found and fixed |

Typical Workflow

Ask your AI agent:

"Check Simple Commenter for open feedback and fix the issues"

The agent will:

1. Call list_projects to find your project
2. Call list_comments with status=todo to get open issues
3. Call get_comment on each to see the element, screenshot, and page URL
4. Mark comments as in_progress while working
5. Fix the code
6. Reply with what was fixed
7. Mark as done

CLI Commands

simple-commenter-mcp init      # Setup wizard — login + pick project
simple-commenter-mcp serve     # Start MCP server (default, used by AI tools)
simple-commenter-mcp doctor    # Health check — verify setup + connectivity
simple-commenter-mcp status    # Show account info + projects
simple-commenter-mcp reset     # Remove config + .mcp.json (clean slate)

login and logout still work as aliases for init and reset.

If not installed globally, prefix with npx @simple-commenter/mcp-server instead.

Changing Your Default Project

To switch to a different project, run init again:

simple-commenter-mcp init

This re-runs the full setup wizard and lets you pick a new default project and preferences.

For a clean start, reset first:

simple-commenter-mcp reset
simple-commenter-mcp init

reset removes your saved config and .mcp.json, so you start fresh.

Configuration

.mcp.json (auto-created by init)

{
  "mcpServers": {
    "simple-commenter": {
      "command": "simple-commenter-mcp",
      "args": ["serve"]
    }
  }
}

Environment variable (CI/Docker)

{
  "mcpServers": {
    "simple-commenter": {
      "command": "npx",
      "args": ["@simple-commenter/mcp-server", "serve"],
      "env": {
        "SIMPLE_COMMENTER_API_TOKEN": "your-token"
      }
    }
  }
}

Authentication priority

The server checks for credentials in this order:

1. --token <token> CLI flag
2. SIMPLE_COMMENTER_API_TOKEN environment variable
3. ~/.simple-commenter/config.json (from init command)

Troubleshooting

Run doctor to diagnose common issues:

simple-commenter-mcp doctor

Common issues:

| Check | Fix | |-------|-----| | Config file not found | Run simple-commenter-mcp init | | No authentication token | Run init or set SIMPLE_COMMENTER_API_TOKEN | | API connection failed | Check your internet connection; verify the API URL with --api-url | | No default project set | Run init and select a project | | .mcp.json not found | Run init from your project root (where package.json or .git is) | | .mcp.json doesn't reference simple-commenter | Run reset then init to recreate it |

Security

• Credentials are stored in ~/.simple-commenter/config.json with chmod 600 (owner-only)
• The server warns if file permissions are too open
• For shared machines, use environment variables instead of the config file
• Add .simple-commenter/ to your .gitignore
• Never commit your API token to version control. Use environment variables in CI/CD pipelines.

Supported AI Tools

The MCP server works with any tool that supports the Model Context Protocol:

• Claude Code — Anthropic's CLI coding agent
• Cursor — AI-powered code editor
• Any MCP-compatible agent — The protocol is open and growing

Development

npm install
npm test