# Hypertxt Python

The official Python client, command-line interface, and MCP server for
[Hypertxt](https://www.hypertxt.ai).

Use it to:

- inspect account credits, projects, article templates, and articles;
- retrieve, generate, export, review, archive, or publish articles;
- query synchronized or live Google Search Console performance;
- give MCP-compatible agents a deliberately scoped content-operations toolset.

## Install

Install the CLI and MCP server into an isolated environment:

```bash
pipx install hypertxt
```

Or run the MCP server without a permanent install:

```bash
uvx --from hypertxt hypertxt-mcp
```

Python applications can install it with:

```bash
python -m pip install hypertxt
```

## Authenticate

Create a named, revocable key in **Hypertxt → Account → Automation**. Keep it
out of source control and chat transcripts:

```bash
export HYPERTXT_API_KEY="htx_replace_with_your_key"
hypertxt status
hypertxt projects
```

The client uses `https://app.hypertxt.ai` by default. Set
`HYPERTXT_API_URL` only when testing against another Hypertxt deployment.

## CLI examples

```bash
# Inspect
hypertxt status
hypertxt articles list --project-id 12 --status awaiting_review
hypertxt articles get 451

# Query GSC
hypertxt gsc query \
  --project-id 12 \
  --group-by query \
  --query-contains "mcp" \
  --start-date 2026-07-01 \
  --end-date 2026-07-25

# Generate after checking credits
hypertxt articles generate \
  --project-id 12 \
  --workflow-id 8 \
  --title "How editorial teams use MCP" \
  --keyword "MCP content workflow"

# Record editorial approval, then create a destination draft
hypertxt articles state 451 reviewed
hypertxt articles publish 451 --integration-id 9 --publish-status draft
```

Pass `--json` before the command for machine-readable output.

## MCP

Start the stdio server:

```bash
hypertxt-mcp
```

Minimal MCP configuration:

```json
{
  "mcpServers": {
    "hypertxt": {
      "command": "uvx",
      "args": ["--from", "hypertxt", "hypertxt-mcp"],
      "env": {
        "HYPERTXT_API_KEY": "${HYPERTXT_API_KEY}"
      }
    }
  }
}
```

The server exposes read tools separately from actions that spend credits,
change editorial state, refresh GSC, or publish. Agents should inspect first
and obtain approval before calling mutating tools.

Client-specific setup and downloadable prompts:

- [MCP overview](https://www.hypertxt.ai/guides/mcp/)
- [OpenClaw](https://www.hypertxt.ai/guides/openclaw/)
- [Claude Code](https://www.hypertxt.ai/guides/claude-code/)
- [Codex](https://www.hypertxt.ai/guides/codex/)
- [Hermes Agent](https://www.hypertxt.ai/guides/hermes-agent/)
- [OpenCode](https://www.hypertxt.ai/guides/opencode/)

### OpenClaw skill

Install the companion portable Hypertxt skill from its public repository:

```bash
openclaw skills install \
  git:simplebytes-com/hypertxt-openclaw@main \
  --as hypertxt
```

Configure the MCP server separately so the skill has tools to call. Start with
the read-only tool filter in the
[OpenClaw guide](https://www.hypertxt.ai/guides/openclaw/), then enable
generation, state changes, GSC refreshes, and publishing when you want the
agent to perform those actions.

## Python

```python
from hypertxt import HypertxtClient

with HypertxtClient() as client:
    status = client.account_status()
    articles = client.list_articles(project_id=12, status="awaiting_review")
```

## Development

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
ruff check src tests
mypy src
pytest -q
python -m build
```

## Security

- Use a different named key for every client or machine.
- Never paste an `htx_…` key into an LLM conversation.
- Prefer environment or secret configuration over command arguments.
- Inspect the full article before changing state or publishing.
- Make generation and live publishing explicit.