Metadata-Version: 2.4
Name: seo-geo-intelligence-mcp
Version: 0.1.1
Summary: SEO + GEO Intelligence MCP
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: license_status.py
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Dynamic: license-file

# SEO + GEO Intelligence MCP

## Core Problem

AI search visibility is becoming a discovery channel, but teams cannot monitor brand mentions across AI engines.

## What This Server Provides

This folder contains a production-minded MCP server scaffold with typed JSON tool responses, connector health metadata, OAuth-oriented configuration, rate-limit guards, stable error envelopes, and deterministic demo data until live vendor integrations are attached.

This server has received a production pass. It now includes local SEO and GEO intelligence models for organic search performance, AI answer visibility, competitor GEO scoring, content gaps, citation opportunities, recommendations, and brand mention monitoring.

## Connectors

- Google Search Console API via OAuth scope `webmasters.readonly`; env prefix `GSC`
- Ahrefs/DataForSEO API via OAuth scope `keywords.read`; env prefix `SEO_DATA`
- Anthropic API via OAuth scope `messages`; env prefix `ANTHROPIC`
- OpenAI API via OAuth scope `responses`; env prefix `OPENAI`
- Perplexity API via OAuth scope `search`; env prefix `PERPLEXITY`
- Google Trends API via OAuth scope `trends.read`; env prefix `GOOGLE_TRENDS`

## MCP Tools

- `get_geo_visibility_score` - Measure brand inclusion across AI answer engines.
- `get_seo_performance` - Blend GSC and backlink/rank data.
- `get_competitor_geo_score` - Compare AI answer visibility.
- `get_content_gaps` - Missing topics and citation opportunities.
- `get_geo_recommendations` - Prioritized content actions.
- `monitor_brand_mentions_in_ai` - Scheduled AI mention monitor.

## Current Local Capabilities

- Scores AI answer visibility across Claude, ChatGPT, and Perplexity-style engines.
- Tracks brand mentions, ranks, citations, and sentiment per keyword/model.
- Blends SEO clicks, impressions, CTR, average position, backlinks, and keyword opportunities.
- Compares competitor GEO visibility by category.
- Identifies missing content topics and citation assets for AI discoverability.
- Generates prioritized GEO recommendations.
- Stages scheduled AI mention monitoring with alert types.

## Test

```powershell
python -m pytest .\tests -q -p no:cacheprovider
```

## Partial Platform Support

Customers only need to connect the search, SEO, and AI visibility providers they actually use. Missing Google Search Console, SEO data provider, OpenAI, Anthropic, Perplexity, or Google Trends credentials do not prevent the server from starting or running local intelligence tools.

Use `get_live_connector_status` to see configured connectors. Use `test_google_search_console_connection`, `test_seo_data_connection`, and `test_ai_visibility_connection` for read-only live smoke checks when those providers are connected.

## Running Locally

`powershell
python -m venv .venv
.\.venv\Scripts\pip install -e .
.\.venv\Scripts\python -m seo_geo_intelligence_mcp.server
`

## Claude Desktop Config

`json
{
  "mcpServers": {
    "seo-geo-intelligence": {
      "command": "python",
      "args": ["-m", "seo_geo_intelligence_mcp.server"],
      "cwd": "D:\CUSTOMS\EARNALL\MCP Servers\06-seo-geo-intelligence"
    }
  }
}
`

## Production Checklist

- Create OAuth 2.1 apps for each connector and set *_CLIENT_ID plus *_CLIENT_SECRET.
- Store refresh tokens in a secrets manager, never in repo files.
- Replace deterministic demo rows in server.py with API adapter calls.
- Persist raw snapshots and normalized warehouse tables for trend analysis.
- Add integration tests with recorded fixtures for every connector.
- Validate every tool in MCP Inspector before publishing.
- Deploy with a /health route through FastMCP streamable HTTP on Railway or Render.

<!-- mcp-name: io.github.atul0016/seo-geo-intelligence -->
