hermes-mcp/SETUP_GUIDE.md

Hermes MCP — Platform Setup Guide

How to obtain credentials and configure each social platform integration.

---

Table of Contents

• TikTok
• Facebook
• Instagram
• LinkedIn
• Twitter / X
• Discord
• Telegram
• WhatsApp
• Email (IMAP/SMTP)
• Obsidian
• Quick Reference: All Env Vars

---

TikTok

Prerequisites

• TikTok Developer account at 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 → 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

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
• 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
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 → 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

# 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=