# Bloghunch MCP Server

Connect your AI assistant directly to your Bloghunch publication to automate content creation, analytics, and distribution.

Supports **two transport modes**:
- **STDIO** — Claude Desktop, Cursor, Windsurf, Zed, VS Code (local, no hosting needed)
- **HTTP** — ChatGPT (remote, requires public HTTPS URL)

---

## Tools Available

| Tool | Description | AI Studio Required? |
|---|---|---|
| `bh_get_stats` | Analytics snapshot (pageviews, subscribers, posts) | No |
| `bh_list_posts` | List posts with status/keyword filter | No |
| `bh_get_post` | Read full content and details of a single post | No |
| `bh_create_post` | Create a post manually as a draft | No |
| `bh_update_post` | Update an existing draft post | No |
| `bh_list_subscribers` | List newsletter subscribers | No |
| `bh_generate_post` | Complete AI generation via topic (SEO brief → RAG → Draft) | **Yes** |
| `bh_generate_ideas` | Brainstorm 5 post angles for any topic | **Yes** |
| `bh_generate_titles` | Generate 5 SEO-optimized title suggestions | **Yes** |
| `bh_generate_seo_brief` | Generate a comprehensive SEO brief | **Yes** |
| `bh_social_echo` | Generate Twitter, LinkedIn, newsletter assets for a post | **Yes** |
| `bh_discover_topics` | Trigger GSC-powered SEO topic discovery | **Yes** |
| `bh_get_topic_discoveries` | List discovered topic opportunities | **Yes** |

> **Note on LTD Users:** Tools marked with "AI Studio Required" will only work if the user has unlocked the **AI Studio Add-on** and configured their own Gemini or OpenAI keys.

---

## Installation — Claude Desktop, Cursor, Windsurf (STDIO)

### 1. Configure `.env`

```bash
cp .env.example .env
```

Fill in:
```
BLOGHUNCH_API_KEY=bh_live_xxxxxxxxxxxx
BLOGHUNCH_SUBDOMAIN=your-subdomain
BLOGHUNCH_API_URL=https://api.bloghunch.com/api/v1
```

Get your API key from [Settings → Developers](https://app.bloghunch.com/app/settings/developers).

### 2. Build

```bash
npm install
npm run build
```

### 3. Client Configuration

Add the following to your AI client's MCP configuration file.
Replace `/absolute/path/to/mcp-server` with the actual path on your machine.

**For Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
**For Cursor** (Cursor Settings → Features → MCP):
**For Windsurf** (`~/.codeium/windsurf/mcp_config.json`):

```json
{
  "mcpServers": {
    "bloghunch": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "BLOGHUNCH_API_KEY": "bh_live_xxxxxxxxxxxx",
        "BLOGHUNCH_SUBDOMAIN": "your-subdomain"
      }
    }
  }
}
```

---

## Installation — ChatGPT (HTTP mode)

ChatGPT requires a **publicly hosted HTTPS server**. Run this on your VPS behind Nginx/Caddy.

### 1. Build

```bash
npm install
npm run build
```

### 2. Set environment variables on your server

```bash
export TRANSPORT=http
export PORT=3001
export MCP_SERVER_URL=https://mcp.yourdomain.com   # public HTTPS URL
export BLOGHUNCH_API_URL=https://api.bloghunch.com/api/v1
```

### 3. Start the server

```bash
npm start
# or: TRANSPORT=http node dist/index.js
```

### 4. Connect in ChatGPT

1. Open ChatGPT → **Settings → Apps & Connectors → Advanced settings** → enable **Developer Mode**
2. Click **Create connector**
3. Enter name: `Bloghunch` and URL: `https://mcp.yourdomain.com`
4. Select **OAuth** as auth method
5. Click **Connect** → log in with your Bloghunch API key
6. Done ✅ — ChatGPT can now use all Bloghunch tools

---

## Local Development

```bash
# STDIO mode
npm run dev

# HTTP mode (test locally)
npm run dev:http
```

---

© 2026 Bloghunch — AI-native blogging platform.