# mcp-seo-tools

An MCP (Model Context Protocol) server that gives AI agents a suite of SEO analysis tools. Analyze any public webpage for meta tags, heading structure, broken links, keyword density, page speed, and sitemap health — all without external API keys.

## Tools

| Tool | Description |
|------|-------------|
| `seo_meta_analyze` | Audit meta tags, Open Graph, and Twitter Card tags with scoring |
| `seo_heading_check` | Validate H1-H6 hierarchy, detect skipped levels and duplicates |
| `seo_link_check` | Find broken links, redirects, and missing anchor text |
| `seo_keyword_density` | Measure keyword frequency and check target keyword placement |
| `seo_page_speed` | Measure TTFB, load time, HTML size, and resource counts |
| `seo_sitemap_parse` | Parse sitemap.xml, check freshness, duplicates, and compliance |

## Requirements

- Node.js 18+
- No API keys needed — all tools use direct HTTP requests and HTML parsing

## Installation

```bash
git clone <repo-url>
cd mcp-seo-tools
npm install
npm run build
```

## Usage with Claude Code

Add to your Claude Code MCP configuration:

```bash
claude mcp add seo-tools node D:/products/mcp-servers/mcp-seo-tools/dist/index.js
```

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "seo-tools": {
      "command": "node",
      "args": ["D:/products/mcp-servers/mcp-seo-tools/dist/index.js"]
    }
  }
}
```

## Tool Details

### seo_meta_analyze

Fetches a URL and inspects all meta-related elements. Checks title length (optimal: 30-60 chars), meta description length (optimal: 120-160 chars), canonical URL, viewport tag, language attribute, Open Graph completeness, and Twitter Card setup. Returns a 0-100 score.

```
Input: { "url": "https://example.com" }
```

### seo_heading_check

Parses all headings on a page and builds a visual hierarchy tree. Flags: missing H1, multiple H1s, skipped heading levels, empty headings, overly long headings (>70 chars), and duplicate headings.

```
Input: { "url": "https://example.com" }
```

### seo_link_check

Extracts all anchor tags from a page, resolves relative URLs, deduplicates, and probes each link with a HEAD request (falling back to GET when needed). Classifies links as ok, broken, redirect, timeout, or error. Reports internal vs. external link ratio.

```
Input: { "url": "https://example.com", "max_links": 100 }
```

### seo_keyword_density

Strips scripts, styles, and navigation, then tokenizes the remaining body text. Computes frequency and density for single words, bigrams, and trigrams (filtering stop words). When a target keyword is provided, checks whether it appears in the title, H1, meta description, and first paragraph.

```
Input: { "url": "https://example.com", "target_keyword": "seo tools" }
```

### seo_page_speed

Measures Time to First Byte and total download time from the server's perspective. Counts external scripts, stylesheets, images, and iframes. Detects render-blocking scripts (missing async/defer), images without alt text or dimensions, missing compression, and absence of lazy loading.

```
Input: { "url": "https://example.com" }
```

### seo_sitemap_parse

Accepts a sitemap URL or any page URL (automatically appends `/sitemap.xml`). Falls back to checking `robots.txt` for a Sitemap directive. Handles both `<sitemapindex>` and `<urlset>` formats. Validates URL count limits, lastmod freshness, duplicate entries, protocol consistency, and trailing slash patterns.

```
Input: { "url": "https://example.com" }
```

## License

MIT