yuukiii/hermes-mcp
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
main
hermes-mcp/SETUP_GUIDE.md
Garfield a5e4c55885 feat(saas): full SquareMCP SaaS platform v1 
- JWT auth with bcrypt password hashing, cookie sessions, forgot/reset password
- Per-user encrypted credential storage (Redis + AES-256-GCM) for all 9 platforms
- Usage tracking with monthly limits per plan (free/starter/growth/enterprise)
- Invoice generation and retrieval (admin + user views)
- Admin panel with customer listing (role-based access)
- Web app UI at app.squaremcp.com — login, dashboard, connections, usage, invoices
- Unified auth middleware: API key, OAuth Bearer, and JWT cookie support
- Facebook Graph API fixes: published_posts endpoint, photo/video post support
- TikTok sandbox compliance: SELF_ONLY privacy for unaudited apps
- URL verification files for TikTok app review
2026-05-13 08:42:33 -04:00

322 lines
9.3 KiB
Markdown
Raw Permalink Blame History

# 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=
```
Reference in New Issue View Git Blame Copy Permalink