# Hermes MCP — Platform Setup Guide

How to obtain credentials and configure each social platform integration.

---

## Table of Contents

- [TikTok](#tiktok)
- [Facebook](#facebook)
- [Instagram](#instagram)
- [LinkedIn](#linkedin)
- [Twitter / X](#twitter--x)
- [Discord](#discord)
- [Telegram](#telegram)
- [WhatsApp](#whatsapp-meta-cloud-api)
- [Email (IMAP/SMTP)](#email-imapsmtp)
- [Obsidian](#obsidian)
- [Quick Reference: All Env Vars](#quick-reference-all-env-vars)

---

## TikTok

### Prerequisites
- TikTok Developer account at [developers.tiktok.com](https://developers.tiktok.com)
- App created in Sandbox or Production mode

### Steps
1. Go to **Developer Portal → Manage Apps → Your App**
2. Add **Login Kit** product → set redirect URI: `https://tiktok.squaremcp.com/auth/tiktok/callback`
3. Add **Content Posting API** product → enable Direct Post
4. Configure scopes: `user.info.basic`, `user.info.profile`, `user.info.stats`, `video.list`, `video.publish`
5. Add domain verification files to site root (TikTok provides `.txt` files)
6. Add sandbox test users under **Sandbox → Target Users**

### Credentials
| Env Var | Source |
|---|---|
| `TIKTOK_CLIENT_KEY` | App → Basic Information → Client Key |
| `TIKTOK_CLIENT_SECRET` | App → Basic Information → Client Secret |
| `TIKTOK_REDIRECT_URI` | `https://tiktok.squaremcp.com/auth/tiktok/callback` |
| `TIKTOK_DEFAULT_ACCESS_TOKEN` | Complete OAuth flow → copy access_token from callback |

---

## Facebook

### Prerequisites
- Facebook Developer account
- Facebook Page (Business/Brand page, not personal profile)
- Admin role on the page

### Steps
1. Go to [developers.facebook.com](https://developers.facebook.com) → **My Apps → Create App**
2. App type: **Business** → add **Pages** product
3. Go to **Graph API Explorer** → select your app → generate token with permissions:
   - `pages_show_list`
   - `pages_read_engagement`
   - `pages_manage_posts`
   - `publish_video`
4. Run `GET /me/accounts` to list pages → copy the **Page Access Token** (not User Token)
5. Copy the **Page ID** from the same response

### Credentials
| Env Var | Source |
|---|---|
| `FACEBOOK_DEFAULT_ACCESS_TOKEN` | Page Access Token from `/me/accounts` |
| `FACEBOOK_DEFAULT_PAGE_ID` | `id` field from `/me/accounts` response |

---

## Instagram

### Prerequisites
- Instagram **Business** or **Creator** account (personal accounts do not work)
- Instagram account connected to a Facebook Page you admin
- Same Facebook App as above, with **Instagram Graph API** product added

### Steps
1. In Instagram app: Profile → Menu → Settings → Account → Switch to Professional Account → **Business**
2. Connect to Facebook Page under **Settings → Creator tools and controls → Set up Instagram Business Profile**
3. In Facebook Developer Portal: add **Instagram Graph API** product to your app
4. Open **Graph API Explorer** → select app → generate token with:
   - `instagram_basic`
   - `instagram_content_publish`
   - `pages_read_engagement`
5. Run: `GET me/accounts?fields=name,instagram_business_account`
6. Find your page → copy `instagram_business_account.id`
7. Copy the **Access Token** from the explorer

### Credentials
| Env Var | Source |
|---|---|
| `INSTAGRAM_DEFAULT_ACCESS_TOKEN` | Graph API Explorer token with `instagram_basic` |
| `INSTAGRAM_DEFAULT_BUSINESS_ACCOUNT_ID` | `instagram_business_account.id` from `/me/accounts` |

---

## LinkedIn

### Prerequisites
- LinkedIn Developer account
- App created at [developer.linkedin.com](https://developer.linkedin.com)

### Steps
1. Create app → add **Sign In with LinkedIn using OpenID Connect** product
2. Set redirect URI: `https://hermes.squaremcp.com/oauth/callback`
3. Request **Share on LinkedIn** product for posting permissions
4. Generate a 3-legged OAuth token with scopes: `openid`, `profile`, `w_member_social`
5. Copy the **Access Token**

### Credentials
| Env Var | Source |
|---|---|
| `LINKEDIN_DEFAULT_ACCESS_TOKEN` | OAuth 2.0 token from LinkedIn Developer Portal |

---

## Twitter / X

### Prerequisites
- Twitter Developer account at [developer.x.com](https://developer.x.com)
- Project and App created

### Steps
1. Create project → create app inside project
2. Enable **User authentication settings** → OAuth 2.0 → set callback URL
3. Permissions: **Read and Write**
4. Go to **Keys and Tokens** → generate **User Access Tokens**
5. Copy **Access Token** and **Access Token Secret**

### Credentials
| Env Var | Source |
|---|---|
| `TWITTER_DEFAULT_ACCESS_TOKEN` | Keys and Tokens → Access Token |
| `TWITTER_DEFAULT_ACCESS_TOKEN_SECRET` | Keys and Tokens → Access Token Secret |
| `TWITTER_DEFAULT_API_KEY` | Keys and Tokens → API Key |
| `TWITTER_DEFAULT_API_SECRET` | Keys and Tokens → API Secret |

---

## Discord

### Prerequisites
- Discord account

### Steps
1. Go to [discord.com/developers/applications](https://discord.com/developers/applications)
2. Click **New Application** → name it (e.g., "SquareMCP Bot")
3. Go to **Bot** tab → click **Add Bot**
4. Under **Privileged Gateway Intents**, enable **MESSAGE CONTENT INTENT**
5. Click **Reset Token** → copy the **Bot Token**
6. Go to **OAuth2 → URL Generator**:
   - Scopes: `bot`
   - Bot Permissions: `Send Messages`, `Read Message History`, `View Channels`
7. Copy the generated URL and open it in browser to invite the bot to your server

### Credentials
| Env Var | Source |
|---|---|
| `DISCORD_DEFAULT_BOT_TOKEN` | Bot tab → Token |

---

## Telegram

### Prerequisites
- Telegram account

### Steps
1. Open Telegram → search **@BotFather**
2. Send `/newbot` → follow prompts → pick username (must end in `bot`)
3. BotFather sends you a **Bot Token** (e.g., `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`)
4. Copy the token

### Credentials
| Env Var | Source |
|---|---|
| `TELEGRAM_DEFAULT_BOT_TOKEN` | BotFather message after creating bot |

---

## WhatsApp (Meta Cloud API)

### Prerequisites
- Meta Business Account
- WhatsApp Business Account (WABA)
- Phone number registered with WhatsApp Business Platform

### Steps
1. Go to [business.facebook.com](https://business.facebook.com) → **WhatsApp → API Setup**
2. Create/select a WhatsApp Business Account
3. Add a phone number → verify via SMS/voice call
4. Go to **Configuration** → generate a **Permanent Access Token**:
   - You need a System User in Meta Business Settings
   - Assign WhatsApp Business Management permission
   - Generate token with `whatsapp_business_management` and `whatsapp_business_messaging`
5. Copy:
   - **Phone Number ID**
   - **WhatsApp Business Account ID** (WABA ID)
   - **Access Token**

### Credentials
| Env Var | Source |
|---|---|
| `WHATSAPP_DEFAULT_ACCESS_TOKEN` | Meta Business → System User → Permanent Token |
| `WHATSAPP_DEFAULT_PHONE_NUMBER_ID` | WhatsApp API Setup → Phone Number ID |
| `WHATSAPP_DEFAULT_BUSINESS_ACCOUNT_ID` | WhatsApp API Setup → WABA ID |

---

## Email (IMAP/SMTP)

### Supported Providers
Yahoo, Gmail, Outlook/Exchange, GoDaddy, any IMAP/SMTP provider.

### Per-Account Env Vars
Replace `{ACCOUNT}` with the account nickname (e.g., `YAHOO`, `GMAIL`, `FETCHERPAY`):

| Env Var | Example |
|---|---|
| `{ACCOUNT}_EMAIL` | `gheron01@yahoo.com` |
| `{ACCOUNT}_PASSWORD` | App-specific password |
| `{ACCOUNT}_IMAP_HOST` | `imap.mail.yahoo.com` |
| `{ACCOUNT}_IMAP_PORT` | `993` |
| `{ACCOUNT}_SMTP_HOST` | `smtp.mail.yahoo.com` |
| `{ACCOUNT}_SMTP_PORT` | `465` or `587` |

### Notes
- Gmail requires an **App Password** (not your regular Google password)
- Yahoo requires an **App Password** generated in Account Security settings
- GoDaddy uses `imap.secureserver.net` and `smtpout.secureserver.net`

---

## Obsidian

### Prerequisites
- Obsidian vault with Syncthing enabled
- Syncthing API key and folder ID

### Steps
1. Install Syncthing on the server hosting Hermes
2. In Obsidian: Settings → Syncthing → copy **API Key** and **Folder ID**
3. Set vault path on the server

### Credentials
| Env Var | Source |
|---|---|
| `OBSIDIAN_VAULT_PATH` | Absolute path to vault on server |
| `SYNCTHING_API_KEY` | Syncthing GUI → Settings → API Key |
| `SYNCTHING_FOLDER_ID` | Syncthing GUI → Folders → Folder ID |
| `SYNCTHING_URL` | `http://localhost:8384` |

---

## Quick Reference: All Env Vars

```bash
# TikTok
TIKTOK_CLIENT_KEY=
TIKTOK_CLIENT_SECRET=
TIKTOK_REDIRECT_URI=https://tiktok.squaremcp.com/auth/tiktok/callback
TIKTOK_DEFAULT_ACCESS_TOKEN=

# Facebook
FACEBOOK_DEFAULT_ACCESS_TOKEN=
FACEBOOK_DEFAULT_PAGE_ID=

# Instagram
INSTAGRAM_DEFAULT_ACCESS_TOKEN=
INSTAGRAM_DEFAULT_BUSINESS_ACCOUNT_ID=

# LinkedIn
LINKEDIN_DEFAULT_ACCESS_TOKEN=

# Twitter/X
TWITTER_DEFAULT_ACCESS_TOKEN=
TWITTER_DEFAULT_ACCESS_TOKEN_SECRET=
TWITTER_DEFAULT_API_KEY=
TWITTER_DEFAULT_API_SECRET=

# Discord
DISCORD_DEFAULT_BOT_TOKEN=

# Telegram
TELEGRAM_DEFAULT_BOT_TOKEN=

# WhatsApp
WHATSAPP_DEFAULT_ACCESS_TOKEN=
WHATSAPP_DEFAULT_PHONE_NUMBER_ID=
WHATSAPP_DEFAULT_BUSINESS_ACCOUNT_ID=

# Email (repeat pattern for each account)
YAHOO_EMAIL=
YAHOO_PASSWORD=
YAHOO_IMAP_HOST=imap.mail.yahoo.com
YAHOO_IMAP_PORT=993
YAHOO_SMTP_HOST=smtp.mail.yahoo.com
YAHOO_SMTP_PORT=465

# Obsidian
OBSIDIAN_VAULT_PATH=
SYNCTHING_API_KEY=
SYNCTHING_FOLDER_ID=
SYNCTHING_URL=http://localhost:8384

# Database
MYSQL_HOST=
MYSQL_PORT=3306
MYSQL_USER=
MYSQL_PASSWORD=

# Redis
REDIS_URL=redis://localhost:6379

# Security
MCP_API_KEY=
CREDENTIAL_ENCRYPTION_KEY=
```