# site-audit-mcp

An [MCP](https://modelcontextprotocol.io) server that gives Claude (or any MCP client) the ability to **audit websites for SEO and technical health**. Ask in plain language, for example *"Audit acme.com and tell me the five fixes that matter most"*, and the assistant crawls the site, checks every page, and explains what to fix.

No API keys and no paid services are needed. It runs locally over studio.

## Tools

| Tool | What it does |
|---|---|
| `audit_page` | On-page SEO audit of one URL: title, meta description, H1/heading structure, image alt text, `lang`, mobile viewport, canonical, Open Graph, `noindex`, word count, HTTPS, page weight, response time. Returns a **0–100 score** and prioritized issues. |
| `check_links` | Collects every link on a page and checks its HTTP status in parallel. Lists broken (4xx/5xx/unreachable) links. Falls back from HEAD to GET for servers that reject HEAD. |
| `check_site_files` | Checks `robots.txt` (presence, `Disallow: /` for all crawlers, declared sitemaps) and the XML sitemap (presence, URL count). |
| `audit_site` | Crawls a site from a start URL (same domain only, up to 50 pages), audits each page, and summarizes the average score, the most common issues, and **duplicate titles and meta descriptions**. |

### Example output

```
# Site audit: https://www.python.org/
Pages audited: 5 · Average score: 97/100

## Most common issues
- ℹ️ `canonical_missing` on 5 page(s): No canonical link tag.
- ⚠️ `h1_multiple` on 3 page(s): Found 5 <h1> headings (recommended 1).
- ℹ️ `heading_skip` on 2 page(s): Heading level jumps from h2 to h4.

## Duplicate meta descriptions
- https://www.python.org/, https://www.python.org/jobs/, ...
```

## Install

Requires Node.js 20 or newer.

```bash
git clone https://github.com/zakyalzd/site-audit-mcp.git
cd site-audit-mcp
npm install
npm run build
```

### Claude Code

```bash
claude mcp add site-audit -- node /absolute/path/to/site-audit-mcp/dist/index.js
```

### Claude Desktop

Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "site-audit": {
      "command": "node",
      "args": ["/absolute/path/to/site-audit-mcp/dist/index.js"]
    }
  }
}
```

## Scoring

Each page starts at 100. Every **error** costs 15 points (for example a missing title, a missing H1, or an HTTP 4xx/5xx), and every **warning** costs 5 (for example a missing meta description, images without alt text, no viewport, or a slow response). **Info** items are suggestions and cost nothing.

## Development

```bash
npm test        # 8 tests against a local HTTP fixture server, using an in-memory MCP client
npm run dev     # run the server from source with tsx
```

Project layout:

- `src/audit.ts`: fetching, HTML analysis, link checking and crawling. It has no MCP dependency.
- `src/server.ts`: MCP tool definitions and markdown formatting.
- `src/index.ts`: stdio entry point.

## Notes

- The server only makes read-only `GET`/`HEAD` requests and sends a `site-audit-mcp` user agent.
- Only `http` and `https` URLs are accepted.
- It fetches whatever URL it is given, including local network addresses. Do not expose it as a public network service without adding an allow-list.

## License

MIT