Markpost

An MCP server that takes Markdown content and syndicates it to Twitter/X, Threads, and a static blog on S3. Designed to be used by AI agents like Claude Code — write a post in Markdown, and Markpost handles the formatting and publishing for each platform.

What it does

• Formats per platform — Strips Markdown to plain text for social media, renders full HTML for blog
• Auto-splits into threads — Long content is split at --- separators or sentence boundaries, respecting each platform's character limit (280 for Twitter, 500 for Threads)
• Previews before publishing — Dry-run tool shows exactly how content will be formatted and split
• Syndicates everywhere at once — Publish to all platforms with a single tool call, or pick specific ones

Tools

Tool	Description
publish_post	Format and publish Markdown to one or more platforms
preview_post	Preview formatting and thread splits without publishing
ping	Health check

Quick start

1. Install

git clone <this-repo> && cd markpost
uv venv && uv pip install -e ".[dev]"

2. Configure API keys

Copy the example config and fill in your credentials:

mkdir -p ~/.markpost
cp config.example.toml ~/.markpost/config.toml

Edit ~/.markpost/config.toml:

[twitter]
consumer_key = "your-consumer-key"
consumer_secret = "your-consumer-secret"
access_token = "your-access-token"
access_token_secret = "your-access-token-secret"

[threads]
access_token = "your-long-lived-access-token"
user_id = "your-threads-user-id"

[blog]
s3_bucket = "my-blog-bucket"
s3_prefix = "posts/"
base_url = "https://blog.example.com"

[blog.aws]
region = "us-east-1"

You can also set a custom config path via the MARKPOST_CONFIG environment variable.

3. Connect to an MCP client

See the sections below for your specific client.

Running the server

stdio mode (default)

stdio is the standard transport for local MCP clients. The server reads JSON-RPC messages from stdin and writes responses to stdout.

uv run python src/markpost/server.py

Or using the FastMCP CLI:

uv run fastmcp run src/markpost/server.py

HTTP mode (remote / SSE)

For remote access or web-based clients, run in HTTP mode:

uv run fastmcp run src/markpost/server.py --transport http --host 0.0.0.0 --port 9000

The server will be available at http://localhost:9000. Clients connect via the Streamable HTTP transport.

Client setup

Claude Code

Register the server with the claude CLI:

claude mcp add markpost -- uv run --directory /path/to/markpost fastmcp run src/markpost/server.py

Verify it's registered:

claude mcp list

The publish_post and preview_post tools will now be available in Claude Code sessions.

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "markpost": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/markpost",
        "fastmcp", "run", "src/markpost/server.py"
      ]
    }
  }
}

Restart Claude Desktop after saving.

Other MCP clients (HTTP)

Start the server in HTTP mode (see above), then point your client at http://localhost:9000.

Getting API keys

Twitter/X

1. Go to the Twitter Developer Portal
2. Create a Project and App
3. Set app permissions to Read and Write
4. Generate your Consumer Key (API Key), Consumer Secret (API Secret), Access Token, and Access Token Secret
5. If you changed permissions after generating tokens, regenerate them

The free tier allows 1,500 tweets/month.

Threads

1. Go to the Meta Developer Dashboard
2. Create a new app and add the Threads API product
3. Your Threads account must be public
4. Complete the OAuth flow to get an access token:
   • Authorize at https://threads.net/oauth/authorize?client_id={app_id}&redirect_uri={uri}&scope=threads_basic,threads_content_publish&response_type=code
   • Exchange the code for a short-lived token at https://graph.threads.net/oauth/access_token
   • Exchange for a long-lived token (60 days) at https://graph.threads.net/access_token?grant_type=th_exchange_token&client_secret={secret}&access_token={short_token}
5. Get your user ID: GET https://graph.threads.net/v1.0/me?access_token={token}

S3 Blog

1. Create an S3 bucket configured for static website hosting
2. Configure your AWS credentials via the standard methods (~/.aws/credentials, environment variables, or IAM role)
3. Set s3_bucket, s3_prefix, and base_url in your config

The base_url should be the public URL where your blog is served (e.g., your CloudFront distribution or S3 website endpoint).

Thread splitting

Long content is automatically split into threads. You control splits two ways:

Explicit separators — Use --- in your Markdown to force a split:

Here is the first tweet in my thread.

---

And here is the second one.

Auto-splitting — If any section exceeds the platform's character limit, it's split at sentence boundaries. If a single sentence is too long, it falls back to word boundaries.

The preview_post tool lets you see exactly how content will be split before publishing.

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest tests/ -v

# Run a specific test file
uv run pytest tests/test_formatter.py -v

Project structure

src/markpost/
  server.py              # FastMCP server — ping, publish_post, preview_post
  config.py              # TOML config loading
  formatter.py           # markdown_to_plain, split_into_thread, markdown_to_html
  publishers/
    twitter.py           # Twitter/X via tweepy
    threads.py           # Threads via httpx (async)
    blog.py              # S3 upload via boto3

License

Apache 2.0