# so-easy-mcp

A full social media management [MCP](https://modelcontextprotocol.io/) server —
post, read, schedule, and analyze across **Facebook, Instagram, LinkedIn,
X/Twitter, Pinterest, and YouTube** from any MCP-compatible AI client. Runs with
a single `npx` command, like Playwright MCP.

> Status: early development. Phase 1 (core server, credentials, tooling) is in
> place. Platform adapters and the setup wizard are being added incrementally.
> See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full design and roadmap.

## Features

- **Six platforms** behind one unified set of MCP tools.
- **Official platform APIs** (OAuth) for stability, with an optional free
  Playwright browser-session mode for X/Twitter.
- **Secure credential storage** in the OS keychain (Windows Credential Manager,
  macOS Keychain, Linux Secret Service) via
  [`@napi-rs/keyring`](https://www.npmjs.com/package/@napi-rs/keyring).
- **Guided setup wizard** with AI-assisted prompts (use Copilot/Claude +
  Playwright to automate developer-portal setup) — _coming soon_.
- **Scheduling** via a platform-independent sidecar process — _coming soon_.

## Requirements

- Node.js 20 or newer.

## Quick start

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "social": {
      "command": "npx",
      "args": ["so-easy-mcp"]
    }
  }
}
```

Then connect your accounts:

```bash
npx so-easy-mcp setup
```

## CLI

```bash
npx so-easy-mcp                 # Start the MCP server (stdio)
npx so-easy-mcp setup           # Interactive setup wizard
npx so-easy-mcp accounts        # List platforms and connection status
npx so-easy-mcp test <platform> # Check stored credentials for a platform
npx so-easy-mcp disconnect <platform> [accountId]

npx so-easy-mcp-scheduler start # Background scheduler sidecar
```

## Platform support

| Platform  | Auth                  | Cost          | Notes                                                  |
| --------- | --------------------- | ------------- | ------------------------------------------------------ |
| Facebook  | OAuth 2.0             | Free          | Posts to a Page (admin access required).               |
| Instagram | OAuth 2.0 (via Meta)  | Free          | Requires a Professional account linked to a FB Page.   |
| LinkedIn  | OAuth 2.0             | Free          | Personal posting; org posting needs Marketing API.     |
| X/Twitter | OAuth 2.0 _or_ browser | $100/mo _or_ free | API mode (paid) or Playwright session mode (free). |
| Pinterest | OAuth 2.0             | Free          | App requires Trial → Standard approval.                |
| YouTube   | OAuth 2.0 (Google)    | Free          | Google Cloud project + YouTube Data API v3 quota.      |

See [ARCHITECTURE.md](./ARCHITECTURE.md) section 13 for per-platform setup
details.

## Development

```bash
npm install         # Install dependencies
npm run build       # Compile TypeScript to dist/
npm run dev         # Run the server with hot reload (tsx)
npm test            # Run the Vitest suite
npm run test:coverage # Run tests with a coverage report
npm run lint        # ESLint
npm run format      # Prettier (write)
```

### Project layout

```
src/
  bin/          CLI entry points (so-easy-mcp, so-easy-mcp-scheduler)
  adapters/     Platform adapters (added per phase)
  credentials/  OS keychain-backed credential store
  tools/        MCP tool definitions
  setup/        Setup wizard + AI prompts (coming soon)
  utils/        Logger, errors
  config.ts     Config schema (zod) + loaders
  server.ts     MCP server factory
tests/          Vitest suite (mirrors src/)
```

## Security

- Credentials are stored in the OS keychain, never in plaintext config files.
- Dependencies are audited (`npm audit`) before installation; the project ships
  with zero known vulnerabilities at release.
- This is not a security boundary. Review your own threat model before granting
  the server access to production social accounts.

## License

[MIT](./LICENSE)