# AgentReacher

[agentreacher.com](https://agentreacher.com)

AgentReacher connects your AI to social media. Open-source platform for AI agents.

The product is intentionally split into two layers:

- the fully open-source product in this repository
- a hosted service layer for managed execution, connected accounts, analytics, and convenience

## Social Integrations

| Platform    | Status |
| ----------- | ------ |
| X (Twitter) | ✅     |
| LinkedIn    | ✅     |
| Bluesky     | ✅     |
| Instagram   | ⏳     |
| TikTok      | ⏳     |
| YouTube     | ⏳     |
| Facebook    | ⏳     |
| Threads     | ⏳     |
| Pinterest   | ⏳     |

## What is in this repo

- TanStack Start app for AgentReacher
- auth, billing, onboarding, workspace, and dashboard flows
- MCP server and CLI
- multi-platform social connection and publishing flows
- post creation, scheduling, and publishing APIs
- basic analytics and calendar views

## Open Source vs Hosted

Everything in AgentReacher is open source in this repository.

The hosted service exists for users who want the completed product experience without assembling the infrastructure themselves.

The hosted layer primarily adds:

- managed deployment and operations
- connected account setup in a ready-to-use product
- managed credentials and third-party service configuration
- convenience, reliability, and reduced setup time

You can self-host the full product, but you will need your own accounts, credentials, and infrastructure for the third-party services AgentReacher integrates with.

## Stack

- React 19
- TanStack Start
- Cloudflare Workers
- InstantDB
- Better Auth
- Stripe
- MCP SDK

## Getting started

### Prerequisites

- Node.js 22+
- pnpm
- an InstantDB app and admin token

### Local development

1. Install dependencies:

```bash
pnpm install
```

2. Copy the environment template:

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

3. Fill in the required values in `.env.local`.

At minimum, local development expects:

- `VITE_INSTANT_APP_ID`
- `INSTANT_APP_ADMIN_TOKEN`
- `BETTER_AUTH_SECRET`
- `BETTER_AUTH_URL`
- `VITE_BETTER_AUTH_URL`

4. Start the app:

```bash
pnpm dev
```

## MCP CLI

The package exposes an `agentreacher` CLI for MCP setup.

### Initialize MCP config

```bash
npx -y agentreacher@latest init
```

For local development inside this repository:

```bash
node bin/agentreacher.mjs init
```

There is a sanitized example config at [`.mcp.json.example`](./.mcp.json.example).

### Available MCP tools

- `list_connected_social_accounts`
- `get_social_connection_oauth_url`
- `connect_bluesky_account`
- `instagram_publish_media`
- `create_text_post`
- `create_image_post`
- `upload_media`
- `schedule_post`
- `publish_post_now`
- `list_posts`
- `submit_feedback`

The tool schema is defined in [`src/lib/agent-mcp-spec.json`](./src/lib/agent-mcp-spec.json).

### Current limitations and notes

- some providers have provider-specific media and OAuth constraints
- self-hosting requires your own platform app credentials and API configuration
- media publishing flows depend on publicly reachable assets where the provider requires them
- media must be reachable at a public `http` or `https` URL
- Instagram video publishing uses the Reels flow
- Bluesky uses direct account connection instead of OAuth

## Deployment

For self-hosting:

- set Cloudflare Worker secrets separately from `wrangler.jsonc`
- replace placeholder vars and routes in [`wrangler.jsonc`](./wrangler.jsonc)
- configure your own InstantDB, Stripe, Better Auth providers, Resend, Upstash, OpenAI, Runware, and social platform apps as needed

## Project policy

- License: [MIT](./LICENSE)
- Contributions: [CONTRIBUTING.md](./CONTRIBUTING.md)
- Security reporting: [SECURITY.md](./SECURITY.md)