BLEX MCP Server

Official MCP server for the BLEX Developer API.

This server is a thin publishing adapter. It does not access the BLEX database or Django internals. It only calls the BLEX Developer API exposed by a BLEX origin.

The intended workflow is: think and draft privately in your agent workspace, then publish to BLEX through drafts, tags, series, images, updates, and explicit publish/delete actions.

Install In Codex

Create a token file first:

mkdir -p "$HOME/.blex"
printf '%s\n' 'blex_pat_...' > "$HOME/.blex/pat"
chmod 600 "$HOME/.blex/pat"

Register the MCP server:

codex mcp add blex \
  -- npx -y blex-mcp \
    --origin https://blex.me \
    --pat-file "$HOME/.blex/pat"

For a self-hosted BLEX instance, change the origin:

codex mcp add blex \
  -- npx -y blex-mcp \
    --origin https://blog.example.com \
    --pat-file "$HOME/.blex/pat"

Configuration

Recommended CLI options:

--origin <url>     BLEX origin. Defaults to https://blex.me.
--pat-file <path>  File containing a BLEX personal access token.
--timeout-ms <ms>  Request timeout. Defaults to 10000.

Environment variables are also supported:

BLEX_ORIGIN
BLEX_PAT_FILE
BLEX_PAT
BLEX_REQUEST_TIMEOUT_MS

Origin priority:

1. --origin
2. BLEX_ORIGIN
3. https://blex.me

Token priority:

1. --pat-file
2. BLEX_PAT_FILE
3. BLEX_PAT
4. configuration error

If a token file is explicitly configured but cannot be read, the server fails instead of falling back to BLEX_PAT.

Tools

BLEX MCP is optimized for a draft-first publishing workflow:

search/list context -> create draft -> get/verify -> update -> explicit publish

Read-only:

blex_get_me
blex_list_my_posts
blex_search_my_posts
blex_get_post
blex_list_tags
blex_list_series

Write:

blex_create_draft
blex_update_post
blex_publish_post
blex_upload_image
blex_delete_post_dry_run
blex_delete_post

blex_delete_post requires confirm: true. Use blex_delete_post_dry_run first.

Recommended Agent Workflows

Create a new public draft:

1. blex_get_me
2. blex_search_my_posts if similar content may already exist
3. blex_list_tags and blex_list_series when taxonomy matters
4. blex_create_draft with Markdown in content; BLEX stores canonical content_html
5. blex_get_post to verify the saved draft

Safely update an existing post:

1. blex_search_my_posts or blex_list_my_posts to find the post
2. blex_get_post to read content_html/rendered_html and updated_at
3. blex_update_post with expected_updated_at
4. blex_get_post again to verify

Publish a draft:

1. blex_get_post
2. Check title, content_html, description, tags, series, slug, and status
3. Ask the user for explicit confirmation
4. blex_publish_post
5. blex_get_post to verify published/scheduled status

Add a generated/local image:

1. blex_upload_image with file_path and alt_text
2. Insert the returned markdown snippet into content; BLEX stores canonical content_html
3. blex_update_post with expected_updated_at

Delete a post:

1. blex_delete_post_dry_run
2. Show the returned post summary to the user
3. Ask for explicit confirmation
4. blex_delete_post with confirm=true

BLEX is the public publishing surface. Do not use it as a private memory store, AI wiki, or scratch note system.

Development

npm install
npm run typecheck
npm test
npm run build

Local Codex registration:

codex mcp add blex-dev \
  -- node /path/to/blex-mcp/dist/cli.js \
    --origin http://localhost:8000 \
    --pat-file "$HOME/.blex/pat"

Release

This package is published to npm as blex-mcp.

Manual release checklist:

npm run release:dry-run
npm publish --access public

The Publish npm package workflow uses npm Trusted Publishing/OIDC. Configure npm package settings with GitHub owner baealex, repository blex-mcp, workflow filename publish.yml, and no environment name unless the workflow is changed to use one.