Skip to main content
Glama
README.md
# Freepost for agents

Use Freepost from Claude Code, Codex, Cursor, or your terminal. The package talks to your Freepost workspace and can work with social accounts you already connected in **Freepost → Accounts**.

## Install

After the npm release, use Node.js 20 or newer and run:

```sh
npx freepost setup
```

Create a workspace API key in **Freepost → Settings → API keys** and enter it at the hidden prompt. Setup checks the key against Freepost, stores it in `~/.config/freepost/credentials` with mode `0600` on Unix, registers MCP, and installs the bundled skill. Restart the agent after setup. Re-running setup preserves other server entries and skips its existing configuration and identical skill files. On a clean machine with no detected clients, setup configures all three.

```sh
npx freepost setup --dry-run
npx freepost setup --only claude,codex,cursor --yes
npx freepost login
npx freepost doctor
```

For non-interactive setup, supply `FREEPOST_API_KEY` through your environment or secrets manager, use a stored key, or pass `--key`. Prefer the environment over `--key` when shell history or process arguments are visible. The key stays out of the MCP configurations. The CLI and stdio server prefer `FREEPOST_API_KEY` over the stored key. Set `FREEPOST_API_URL` (or `FREEPOST_BASE_URL`) to an HTTPS service base URL or an HTTP loopback base URL for local testing. The default is `https://freepost.io`.

Doctor checks authenticated MCP initialization and reports both CLI and server versions. It reports `null` for the key's scopes and plan, which the current server does not disclose on initialization. Review them in Freepost Settings.

### Claude Code

```sh
npx freepost setup --only claude
```

Setup runs `claude mcp add freepost -s user -- npx -y freepost mcp` when the Claude CLI is on PATH. The fallback writes the user MCP entry in `~/.claude.json`. The skill installs to `~/.claude/skills/freepost`. With `CLAUDE_CONFIG_DIR` set, setup uses that directory for the user config and skill.

### Codex

```sh
npx freepost setup --only codex
```

Setup uses `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) and installs the skill to `~/.agents/skills/freepost`. To configure MCP manually after `npx freepost login`, add:

```toml
[mcp_servers.freepost]
command = "npx"
args = ["-y", "freepost", "mcp"]
env_vars = ["FREEPOST_API_KEY", "FREEPOST_API_URL", "FREEPOST_BASE_URL"]
```

### Cursor

```sh
npx freepost setup --only cursor
```

Setup registers the server in `~/.cursor/mcp.json` and installs the skill to `~/.cursor/skills/freepost`. To configure MCP manually after `npx freepost login`, merge this entry into your existing config:

```json
{
  "mcpServers": {
    "freepost": {
      "command": "npx",
      "args": ["-y", "freepost", "mcp"]
    }
  }
}
```

### Skill-only installation

Once the standalone source repository is public, install the [Freepost skill](skills/freepost/SKILL.md) through the skills CLI:

```sh
npx skills add Youhai020616/freepost-agent
```

The skill works with the local stdio server or a direct connection to [Freepost remote MCP](https://freepost.io/api/mcp) using Streamable HTTP and OAuth. See the bundled [Claude Code](skills/freepost/examples/claude-code.md), [Codex](skills/freepost/examples/codex.md), and [MCP-only](skills/freepost/examples/mcp-only.md) examples.

## Use the CLI

```sh
npx freepost --help
npx freepost accounts
npx freepost rules xiaohongshu
npx freepost posts --status draft --limit 10
npx freepost upload ./cover.png
npx freepost validate @draft.json
npx freepost draft @draft-with-idempotency-key.json
npx freepost post <post-id>
```

`draft`, `validate`, and `update` accept an inline JSON object, `@FILE`, or `-` for stdin. See the [Freepost API contract](https://freepost.io/api/v1/openapi.json) for input fields. For example, a draft's JSON can include `content`, `targetAccounts` (Freepost account IDs), optional `title` and `mediaIds`, and an `idempotencyKey` you retain for retries.

Ask the user to approve the exact content, destination, and time before publishing or scheduling. The bundled stdio tools require `confirmed: true`, and the CLI requires `--confirmed`. Freepost enforces `publish:write` for publishing and `schedules:write` for scheduling. Select those scopes when creating a key that needs them.

```sh
npx freepost publish <post-id> --idempotency-key <publish-key> --confirmed
npx freepost schedule <post-id> 2099-07-02T09:00:00+08:00 --idempotency-key <schedule-key> --confirmed
npx freepost publication <delivery-id>
```

Reuse the same idempotency key for the same request after a lost response. Check a pending or unknown delivery with `publication` before taking further action.

## MCP tools

`freepost mcp` discovers the service's tool and resource schemas over Streamable HTTP. These are the tools implemented by the Freepost remote MCP API at this release:

| Tools | CLI |
| --- | --- |
| `accounts_list`, `usage_get`, `platforms_rules` | `accounts`, `usage`, `rules` |
| `media_upload` | `upload` accepts a local file or a public URL |
| `posts_validate`, `posts_create`, `posts_update`, `posts_delete` | `validate`, `draft`, `update`, `delete` |
| `posts_get`, `publications_get` | `post`, `publication` |
| `posts_publish`, `posts_schedule`, `schedules_cancel` | `publish`, `schedule`, `cancel` |

The CLI's `posts` and `media` list commands use the corresponding REST endpoints. The upload tool takes a URL or base64 bytes, and the CLI can encode a local file for it. Analytics is outside the current remote MCP tool surface. Draft text comes from the user's agent.

## Build and test

From a Freepost monorepo checkout:

```sh
pnpm install --frozen-lockfile
pnpm --filter ./packages/freepost-agent build
pnpm --filter ./packages/freepost-agent test
pnpm platform-rules:check
node packages/freepost-agent/dist/cli.js --help
```

From a standalone source checkout, use `npm install`, `npm test`, and `npm run build`. The monorepo generates the bundled platform files from the platform skills and shared content rules. Change those upstream sources and regenerate before exporting a new version.