DEV Community: appierun

Convert CSV and JSON to Markdown Tables for LLM Prompts and Chatbot Knowledge With Python (Escaping, Ragged Rows, Nested Fields)

appierun — Sun, 01 Nov 2026 16:01:50 +0000

Pasting a spreadsheet export into a prompt, a README or a chatbot knowledge file usually goes one of two ways: raw CSV that is hard for a person to review, or a hand-made Markdown table that breaks the moment a cell contains a pipe character. This post walks through a small, dependency-free Python script that turns CSV files and JSON arrays into Markdown tables and handles the cases that break naive converters.

Disclosure: Appie.run publishes this post. Appie has free CSV and JSON to Markdown converters, mentioned near the end. The script below has no dependency on them, and it uses only the Python standard library.

Earlier posts in this series cover converting PDFs to Markdown for RAG and converting Notion to Markdown.

What breaks naive converters

The one-liner "| " + " | ".join(row) + " |" works until your data meets the real world:

Pipes inside cells. A value like has a | pipe adds a column and shifts everything after it.
Newlines inside quoted CSV cells. A multi-line note ends the table row early.
Ragged rows. Exports often have trailing rows with fewer fields, or completely empty rows.
Different delimiters. European spreadsheet exports often use semicolons.
A byte order mark. Excel's "CSV UTF-8" export starts with a BOM, which ends up glued to your first header.
JSON records with different keys. The second object has a field the first one lacks.
Nested values. A list of tags or an address object inside a record.

The script

Save this as to_md.py. It was tested with Python 3.13 on the cases below.

import csv
import json
import sys
from pathlib import Path


def escape_cell(value):
    """Make one value safe for a Markdown table cell."""
    if value is None:
        return ""
    if isinstance(value, (dict, list)):
        value = json.dumps(value, ensure_ascii=False)
    text = str(value)
    text = text.replace("\\", "\\\\").replace("|", "\\|")
    return " ".join(text.split())  # newlines and tabs become single spaces


def rows_to_markdown(header, rows):
    lines = [
        "| " + " | ".join(escape_cell(h) for h in header) + " |",
        "| " + " | ".join("---" for _ in header) + " |",
    ]
    for row in rows:
        cells = list(row) + [""] * (len(header) - len(row))  # pad short rows
        lines.append("| " + " | ".join(escape_cell(c) for c in cells[: len(header)]) + " |")
    return "\n".join(lines)


def csv_to_markdown(path, max_rows=None):
    with open(path, newline="", encoding="utf-8-sig") as f:
        sample = f.read(4096)
        f.seek(0)
        try:
            dialect = csv.Sniffer().sniff(sample, delimiters=",;\t")
        except csv.Error:
            dialect = csv.excel
        reader = csv.reader(f, dialect)
        header = next(reader)
        rows = []
        for i, row in enumerate(reader):
            if max_rows is not None and i >= max_rows:
                break
            if any(cell.strip() for cell in row):
                rows.append(row)
    return rows_to_markdown(header, rows)


def json_to_markdown(path, max_rows=None):
    data = json.loads(Path(path).read_text(encoding="utf-8"))
    if isinstance(data, dict):
        # a dict of lists: render each list under its own heading
        parts = []
        for key, value in data.items():
            parts.append(f"## {key}\n")
            if isinstance(value, list) and value and all(isinstance(v, dict) for v in value):
                parts.append(records_to_markdown(value, max_rows))
            else:
                parts.append(escape_cell(value))
            parts.append("")
        return "\n".join(parts).strip()
    return records_to_markdown(data, max_rows)


def records_to_markdown(records, max_rows=None):
    if max_rows is not None:
        records = records[:max_rows]
    header = []
    for rec in records:  # union of keys, first-seen order
        for key in rec:
            if key not in header:
                header.append(key)
    rows = [[rec.get(k) for k in header] for rec in records]
    return rows_to_markdown(header, rows)


if __name__ == "__main__":
    src = sys.argv[1]
    limit = int(sys.argv[2]) if len(sys.argv) > 2 else None
    if src.lower().endswith(".json"):
        print(json_to_markdown(src, limit))
    else:
        print(csv_to_markdown(src, limit))

Run it with a file and an optional row limit:

python3 to_md.py plans.csv
python3 to_md.py leads.json 25

How each problem is handled

Pipes and backslashes are escaped in escape_cell, so a | b renders as one cell. Backslashes are escaped first so an existing \ does not swallow the escape.
Newlines and tabs collapse to single spaces with " ".join(text.split()). Markdown table cells cannot hold line breaks without HTML, and a prompt rarely needs them.
Ragged rows are padded with empty cells up to the header length and trimmed if they are longer. Rows where every cell is blank are skipped.
Delimiters are detected by csv.Sniffer from the first 4 KB, limited to comma, semicolon and tab, with a fallback to standard CSV if detection fails.
The BOM is removed by opening the file with encoding="utf-8-sig".
Different keys in JSON records are merged into one header in first-seen order, and missing values become empty cells.
Nested values (lists and objects) are written as compact JSON inside the cell. A top-level JSON object of lists becomes one ## heading per key, with a table under each list of records.

Test it on the awkward cases

printf 'plan,price_usd,notes\nStarter,19,"2,000 credits"\nStandard,49,"has a | pipe\nand a newline"\n,,\nFree,0\n' > plans.csv
python3 to_md.py plans.csv

Output:

| plan | price_usd | notes |
| --- | --- | --- |
| Starter | 19 | 2,000 credits |
| Standard | 49 | has a \| pipe and a newline |
| Free | 0 |  |

The quoted comma stayed in its cell, the pipe was escaped, the newline became a space, the blank row was dropped and the short Free row was padded.

A semicolon file:

printf 'name;score\nA;1\nB;2\n' > semi.csv
python3 to_md.py semi.csv

| name | score |
| --- | --- |
| A | 1 |
| B | 2 |

JSON records with different keys and a nested list:

echo '[{"name":"Ana","company":"Acme","tags":["saas","eu"]},{"name":"Ben","title":"PM"}]' > leads.json
python3 to_md.py leads.json

| name | company | tags | title |
| --- | --- | --- | --- |
| Ana | Acme | ["saas", "eu"] |  |
| Ben |  |  | PM |

A JSON object of lists:

echo '{"plans":[{"name":"Starter","credits":2000},{"name":"Standard","credits":5000}],"currency":"USD"}' > nested.json
python3 to_md.py nested.json

## plans

| name | credits |
| --- | --- |
| Starter | 2000 |
| Standard | 5000 |

## currency

USD

Is Markdown the right format for a prompt?

It depends on what you are optimising. We measured one case on our own machine: 50 records with four short fields came to 3,280 characters as JSON, 1,202 as CSV and 1,686 as a Markdown table. You can reproduce it with this snippet next to to_md.py:

import csv, io, json
from to_md import records_to_markdown

rows = [{"id": i, "name": f"user{i}", "plan": "Starter", "credits": 2000} for i in range(50)]
buf = io.StringIO()
w = csv.DictWriter(buf, fieldnames=rows[0].keys())
w.writeheader()
w.writerows(rows)
print(len(json.dumps(rows)), len(buf.getvalue()), len(records_to_markdown(rows)))

So for this data, CSV was the most compact and JSON the largest. Characters are not tokens, and your numbers will differ with your data and tokenizer, so measure your own case. Practical rules we use:

Use Markdown when the table sits inside prose (a README, a doc page, a chatbot knowledge file a person will review), or when you want the model and the reader to see the same thing.
Use CSV when the table is large and you only care about size.
Keep JSON when values are deeply nested or when the model must return the same structure.
Limit rows. The optional row limit exists because the right answer for a 20,000-row export is usually a sample plus a summary, not the whole file.

When you do not want to run a script

Appie has two free browser tools for one-off conversions:

Convert CSV to Markdown: paste a CSV export or upload the file, and the first row becomes the table header.
Convert JSON to Markdown: paste JSON or upload a .json file. Arrays of objects become tables and nested objects become headings.

Both ask for a Cloudflare Turnstile check before each run, and the pages say the file or paste is converted for that request and not saved to an Appie account. For anything repeatable, or for data you would rather not paste into a website, use the script.

If the Markdown is headed for a chatbot, Appie's AI Chatbots app can also take CSV files, text and URLs as knowledge directly, and you can add content from Claude Code or Cursor through the add_chatbot_content tool on Appie's MCP server.

Honest limits of Appie's converters

One file per run, by hand. There is no batch mode on the tool pages, and each run needs a fresh captcha check.
No control over escaping or row limits is described on the pages. If you need a specific output format, the script gives you that control.

FAQ

Why not use pandas to_markdown()?
It works well if pandas is already installed; it needs the extra tabulate package. The script above has no dependencies, which matters in small containers, CI jobs and serverless functions.

How do I keep line breaks inside a cell?
Replace the newline with <br> instead of a space in escape_cell. Many Markdown renderers, including GitHub's, show it as a line break inside the cell. LLMs read it fine, but it adds characters.

What about very wide tables?
Split them. A table with 30 columns is hard for people and models to read. Pick the columns the prompt actually needs.

Does the script handle Excel files?
No. Export the sheet as CSV first, or read it with openpyxl and pass the rows to rows_to_markdown.

If you want a website chatbot trained on files like these, you can try Appie's AI Chatbots on the Free plan (500 credits, no credit card) at appie.run.

RG, Founder, Appie.run

How to Compare Two XML Sitemaps Before and After a Site Migration With Python (Find Removed URLs and Missing Redirects)

appierun — Sat, 31 Oct 2026 15:57:04 +0000

A site migration (new domain, new CMS, new URL structure) is where search traffic quietly goes missing. Pages that existed before the move disappear from the new site, and nobody notices until rankings drop. Your old and new XML sitemaps are the quickest record of what changed. This post walks through a small Python script that diffs them, follows sitemap indexes, handles a domain change, and checks every removed URL against your redirect map.

Disclosure: Appie.run publishes this post. Appie has free sitemap tools, mentioned near the end. The script below has no dependency on them, and it uses only the Python standard library.

Earlier posts in this series cover generating a sitemap for a static site and validating a sitemap. Run the validator on both files first if you are not sure they are well formed.

What the script answers

Which URLs are in the old sitemap but not the new one (removed)?
Which are new (added)?
Which survived (kept)?
For every removed URL, is there a redirect in your map, and does the target actually exist in the new sitemap?

Question 4 is the one that saves you. A redirect pointing at a page that was never built is as bad as no redirect.

Before you run it

Save the old sitemap before launch day. Once the new site is live, the old sitemap.xml is usually gone. Download it (and every child sitemap) while you still can.
Export your redirect map as a two-column CSV: old_url,new_url. Most migration plans already have one in a spreadsheet.

The script

Save this as sitemap_diff.py:

#!/usr/bin/env python3
"""Compare two XML sitemaps (before and after a site migration)."""
import argparse
import csv
import gzip
import sys
import urllib.request
import xml.etree.ElementTree as ET
from urllib.parse import urlsplit, urlunsplit

NS = "{http://www.sitemaps.org/schemas/sitemap/0.9}"
UA = "sitemap-diff/1.0 (+https://example.com/contact)"


def read_source(src):
    """Return raw bytes from a URL or a local file path."""
    if src.startswith(("http://", "https://")):
        req = urllib.request.Request(src, headers={"User-Agent": UA})
        with urllib.request.urlopen(req, timeout=30) as resp:
            data = resp.read()
    else:
        with open(src, "rb") as fh:
            data = fh.read()
    if data[:2] == b"\x1f\x8b":  # gzip magic number
        data = gzip.decompress(data)
    return data


def collect_urls(src, seen=None, depth=0):
    """Return the set of page URLs in a sitemap, following sitemap indexes."""
    seen = seen if seen is not None else set()
    if src in seen or depth > 3:
        return set()
    seen.add(src)
    root = ET.fromstring(read_source(src))
    tag = root.tag.replace(NS, "")
    locs = [el.text.strip() for el in root.iter(NS + "loc") if el.text]
    if tag == "sitemapindex":
        urls = set()
        for child in locs:
            urls |= collect_urls(child, seen, depth + 1)
        return urls
    if tag == "urlset":
        return set(locs)
    raise ValueError(f"{src}: root element is <{tag}>, expected urlset or sitemapindex")


def normalise(url, old_host=None, new_host=None, ignore_slash=True):
    """Make URLs comparable: lowercase host, optional host swap, trailing slash."""
    parts = urlsplit(url)
    host = parts.netloc.lower()
    if old_host and host == old_host.lower():
        host = new_host.lower()
    path = parts.path or "/"
    if ignore_slash and len(path) > 1:
        path = path.rstrip("/")
    return urlunsplit((parts.scheme.lower(), host, path, parts.query, ""))


def load_redirects(path):
    """Read a two-column CSV of old_url,new_url."""
    with open(path, newline="", encoding="utf-8") as fh:
        return {row[0].strip(): row[1].strip() for row in csv.reader(fh) if len(row) >= 2}


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("before", help="old sitemap: URL or file")
    ap.add_argument("after", help="new sitemap: URL or file")
    ap.add_argument("--old-host", help="host used before the move, e.g. www.old.com")
    ap.add_argument("--new-host", help="host used after the move, e.g. www.new.com")
    ap.add_argument("--redirects", help="CSV of old_url,new_url to check removed URLs against")
    ap.add_argument("--out", default="sitemap-diff.csv", help="where to write the report")
    args = ap.parse_args()

    if bool(args.old_host) != bool(args.new_host):
        ap.error("--old-host and --new-host go together")

    before_raw = collect_urls(args.before)
    after_raw = collect_urls(args.after)

    before = {normalise(u, args.old_host, args.new_host): u for u in before_raw}
    after = {normalise(u): u for u in after_raw}

    kept = before.keys() & after.keys()
    removed = before.keys() - after.keys()
    added = after.keys() - before.keys()

    redirects = load_redirects(args.redirects) if args.redirects else {}
    after_norm = set(after.keys())

    rows = []
    for key in sorted(removed):
        old = before[key]
        target = redirects.get(old, "")
        if not redirects:
            note = ""
        elif not target:
            note = "no redirect mapped"
        elif normalise(target) not in after_norm:
            note = "redirect target not in new sitemap"
        else:
            note = "ok"
        rows.append(("removed", old, target, note))
    rows += [("added", after[k], "", "") for k in sorted(added)]
    rows += [("kept", after[k], "", "") for k in sorted(kept)]

    with open(args.out, "w", newline="", encoding="utf-8") as fh:
        writer = csv.writer(fh)
        writer.writerow(["status", "url", "redirect_to", "note"])
        writer.writerows(rows)

    print(f"before: {len(before)}  after: {len(after)}")
    print(f"kept: {len(kept)}  added: {len(added)}  removed: {len(removed)}")
    if redirects:
        problems = sum(1 for r in rows if r[0] == "removed" and r[3] != "ok")
        print(f"removed URLs without a valid redirect: {problems}")
    print(f"report: {args.out}")
    return 1 if redirects and problems else 0


if __name__ == "__main__":
    sys.exit(main())

What each part does

read_source accepts a URL or a local file and decompresses .gz sitemaps by checking the gzip magic bytes rather than trusting the file name.
collect_urls reads the root element. A <urlset> returns its <loc> values. A <sitemapindex> makes the function fetch each child sitemap and merge the results. The seen set and depth limit stop a loop if an index lists itself.
normalise makes URLs comparable. It lowercases the scheme and host, drops fragments, treats /page and /page/ as the same, and, if you pass --old-host and --new-host, rewrites the old host so https://www.old-shop.com/pricing/ matches https://www.new-shop.com/pricing.
The diff is three set operations on the normalised keys. The original URLs are kept for the report, so you see exactly what each sitemap listed.
Redirect checks run only when you pass --redirects. Each removed URL is marked ok, no redirect mapped, or redirect target not in new sitemap.
Exit code is 1 when any removed URL lacks a valid redirect, so you can fail a CI job on it.

Run it

A small example with an old site at www.old-shop.com and a new one at www.new-shop.com, where the new sitemap is an index pointing to a child file:

python3 sitemap_diff.py old-sitemap.xml https://www.new-shop.com/sitemap_index.xml \
  --old-host www.old-shop.com --new-host www.new-shop.com \
  --redirects redirects.csv

Output:

before: 4  after: 5
kept: 2  added: 3  removed: 2
removed URLs without a valid redirect: 1
report: sitemap-diff.csv

And sitemap-diff.csv:

status,url,redirect_to,note
removed,https://www.old-shop.com/about-us,https://www.new-shop.com/about,redirect target not in new sitemap
removed,https://www.old-shop.com/blog/launch-post,https://www.new-shop.com/blog/launch,ok
added,https://www.new-shop.com/blog/launch,,
added,https://www.new-shop.com/company,,
added,https://www.new-shop.com/integrations,,
kept,https://www.new-shop.com/,,
kept,https://www.new-shop.com/pricing,,

The first row is the kind of bug this catches: the redirect map sends /about-us to /about, but the new site calls that page /company. Fix the map before launch, not after.

Notice that /pricing/ and /pricing count as kept because of the trailing slash rule. If your new site really treats them as different pages, run without that rule (set ignore_slash=False in normalise).

Optional: check what the live URLs actually do

The map says what should happen. After launch, check what does happen. This second script reads the report and requests each removed URL without following redirects, so you see the first hop:

#!/usr/bin/env python3
"""For each removed URL in sitemap-diff.csv, request it and report where it lands."""
import csv
import sys
import urllib.error
import urllib.request


class NoFollow(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, *args, **kwargs):
        return None  # stop at the first hop so we can see the status code


opener = urllib.request.build_opener(NoFollow)


def first_hop(url, method="HEAD"):
    req = urllib.request.Request(url, method=method, headers={"User-Agent": "sitemap-diff/1.0"})
    try:
        with opener.open(req, timeout=20) as resp:
            return resp.status, ""
    except urllib.error.HTTPError as err:  # 3xx lands here because we refuse to follow
        if method == "HEAD" and err.code in (405, 500, 501):
            return first_hop(url, "GET")  # some servers reject HEAD
        return err.code, err.headers.get("Location", "")
    except urllib.error.URLError as err:
        return 0, str(err.reason)


report = sys.argv[1] if len(sys.argv) > 1 else "sitemap-diff.csv"
with open(report, newline="", encoding="utf-8") as fh:
    for row in csv.DictReader(fh):
        if row["status"] != "removed":
            continue
        code, location = first_hop(row["url"])
        flag = "" if code in (301, 308) else "  <-- check"
        print(f"{code} {row['url']} -> {location}{flag}")

Example output (illustrative URLs):

301 https://www.old-shop.com/blog/launch-post -> https://www.new-shop.com/blog/launch
404 https://www.old-shop.com/about-us ->   <-- check

Anything that is not a 301 or 308 gets flagged. A 302 is a temporary redirect, which is usually not what you want for a permanent move, and a 200 means the old page still serves content. Some servers reject HEAD requests, so the script retries those with GET. Keep the request rate polite on large sites; for tens of thousands of URLs, add a short time.sleep between requests or run it on a sample.

Wire it into a pre-launch check

# fails the job if any removed URL lacks a valid redirect
python3 sitemap_diff.py old-sitemap.xml staging-sitemap.xml \
  --old-host www.old-shop.com --new-host staging.new-shop.com \
  --redirects redirects.csv --out diff.csv

Running it against the staging sitemap on every deploy means a page dropped by a template change shows up the same day.

Known limits

A sitemap is not the whole site. Pages that were never in the old sitemap won't be checked. Combine this with a crawl or your analytics' top landing pages.
Query strings are compared as-is. If the old site used ?id=12 and the new one uses clean paths, rely on the redirect map rather than the kept count.
Relative <loc> values inside an index are read as local paths. The sitemap protocol expects absolute URLs, so this only matters for hand-made test files.
Memory. Everything is held in sets. That is fine for a few hundred thousand URLs; beyond that, stream to disk.

When a script is more than you need

For a one-off check, Appie's free tools do the core steps in the browser:

Sitemap URLs Comparison Tool takes two sitemaps, by URL or pasted XML, and reports how many URLs stayed, which were added and which were removed. The first sitemap is treated as the before state.
Sitemap URL Extractor lists one URL per line from a sitemap. Given a sitemap index, it lists the child sitemaps, so you run it again on each child.
Sitemap Finder and Checker finds sitemaps through robots.txt and the usual paths, which helps when you don't know where the old site kept them.

Each asks for a captcha before running. They don't check redirect maps or host changes, which is where the script above earns its keep.

RG, Founder, Appie.run

Create and Track Short Links From Claude Code or Cursor With an MCP Server (Appie, Bitly, Dub, Short.io)

appierun — Fri, 30 Oct 2026 16:02:40 +0000

If you ship release notes, changelogs or launch posts from your editor, the short link is usually the last manual step: open a shortener in a browser tab, paste the URL, copy the result, come back. With an MCP server, your coding agent can create the link and later tell you how many clicks it got, in the same session where you wrote the post.

This walkthrough shows the setup for four link shorteners that publish an MCP server: Appie.run, Bitly, Dub and Short.io. It covers the config for Claude Code and Cursor, the prompts that work, and the limits of each.

Plan details and prices are as of 29 Oct 2026, checked on each vendor's own docs and pricing pages that day.

Disclosure: Appie.run publishes this post, and one of the four servers is ours. We compared shorteners more broadly (not just MCP) in Bitly alternatives in 2026.

The four servers at a glance

Endpoint: Appie.run: https://appie.run/mcp; Bitly: https://api-ssl.bitly.com/v4/mcp; Dub (Links): https://mcp.dub.sh/mcp/dub-links; Short.io: https://ai-assistant.short.io/mcp (via npx mcp-remote)
Auth: Appie.run: OAuth 2.1 (ChatGPT) or esk_ project API key; Bitly: OAuth 2.1 or Bitly API token; Dub (Links): Dub API key in Mcp-Dub-Token header; Short.io: Short.io API key
Custom domain: Appie.run: No, links use s.appie.run; Bitly: Yes, on Growth and up; Dub (Links): Yes; Short.io: Yes
Edit or delete existing links via MCP: Appie.run: Not in the documented tools; Bitly: See Bitly's MCP tools reference; Dub (Links): Dub says the server lets you "programmatically manage your links"; check its tool list; Short.io: No, per Short.io's docs
Entry price: Appie.run: Free plan, 500 credits, no card; links cost 1 credit, clicks 0.001 credit each; Bitly: Bitly support says MCP is "available with some paid plans"; Core is $10/month billed annually; Dub (Links): Free plan (25 new links/month); Pro $27/month; Short.io: Free plan (1,000 branded links total); Hobby $5/month

Prerequisites

Claude Code or Cursor with MCP support.
An account with the shortener and an API key or OAuth access.
Keep keys in environment variables. Do not commit them to a shared repo.

Option 1: Appie.run

Appie's MCP server exposes two link tools, documented at appie.run/docs/mcp:

create_short_link: Arguments: long_url, optional code (custom slug); Cost: 1 credit per link; each click on the link costs 0.001 credit
link_stats: Arguments: id or code; Cost: 0 credits to read

Reads are free. Writes spend the project's credits first, then the owner's.

Claude Code:

export APPIE_API_KEY=esk_your_project_key
claude mcp add --transport http appie https://appie.run/mcp \
  --header "Authorization: Bearer $APPIE_API_KEY"

Cursor (~/.cursor/mcp.json or .cursor/mcp.json in the project):

{
  "mcpServers": {
    "appie": {
      "url": "https://appie.run/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Appie's docs also accept the key in an X-Api-Key header if your client prefers that.

Prompts that work:

Create a short link for https://example.com/blog/v2-release?utm_source=devto&utm_medium=post
with the code v2-devto.

Get link_stats for the code v2-devto and tell me the click count.

What the links give you: links live on the s.appie.run domain, and the URL Shortener page lists clicks and unique visitors over the last 30 days, lifetime totals, and device and location breakdowns through the stats API.

Limits: no custom domain, and the MCP tools cover create and read only. If you need branded domains or bulk edits, one of the other three is a better fit. The same MCP server also covers Appie's other apps (articles, chatbots, Reddit and LinkedIn research), which matters only if you want one server for several marketing jobs. We wrote about that in One MCP server for your marketing agent.

Option 2: Bitly

Bitly hosts its server at https://api-ssl.bitly.com/v4/mcp. Its developer docs list setup guides for ChatGPT, Claude (web, desktop and Claude Code), Cursor, VS Code and Windsurf, with OAuth 2.1 recommended and an API token as the fallback.

Claude Code or Cursor (from Bitly's docs; Claude Code reads ~/.claude/mcp.json, Cursor reads ~/.cursor/mcp.json):

{
  "mcpServers": {
    "Bitly": {
      "type": "http",
      "url": "https://api-ssl.bitly.com/v4/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_BITLY_AUTH_TOKEN"
      }
    }
  }
}

Drop the headers block to use OAuth instead.

Pricing note: Bitly's support page says the MCP server is "available with some paid plans", so confirm yours before building a workflow around it. On Bitly's pricing page, Core is $10/month (billed annually, 100 links/month, 30 days of click data), Growth is $29/month (500 links/month, branded links, 4 months of data) and Premium is $199/month (3,000 links/month, city and device data). The Free plan allows 5 links a month.

Option 3: Dub

Dub runs two MCP servers: one for its partner program product and one for links. For short links you want https://mcp.dub.sh/mcp/dub-links. Dub's docs pass the API key in an Mcp-Dub-Token header.

Claude Code:

claude mcp add dub-links --transport http https://mcp.dub.sh/mcp/dub-links \
  --header "Mcp-Dub-Token: $DUB_API_KEY"

Cursor:

{
  "mcpServers": {
    "dub-links": {
      "url": "https://mcp.dub.sh/mcp/dub-links",
      "headers": {
        "Mcp-Dub-Token": "dub_xxxxxx"
      }
    }
  }
}

Pricing: Dub's Links pricing page lists a Free plan (25 new links/month, 1,000 tracked events/month, 30-day retention, API access, 3 custom domains), Pro at $27/month (12K new links/year, 1-year retention, 10 custom domains) and Business at $81/month. Dub's launch post says its MCP server is generally available on all Dub plans; confirm that the Links server is included on yours before you rely on it.

Option 4: Short.io

Short.io's docs connect through mcp-remote:

{
  "mcpServers": {
    "shortio": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://ai-assistant.short.io/mcp",
        "--header",
        "Authorization: ${SHORTIO_API_KEY}"
      ],
      "env": {
        "SHORTIO_API_KEY": "sk_secret_key"
      }
    }
  }
}

Short.io's docs show creating links on your own domain with a custom slug, searching links, and pulling link and domain statistics (countries, browsers, operating systems, UTM campaigns). One limit they state plainly: with the current MCP implementation you cannot edit or delete an existing link; you remove it in the dashboard and create a new one.

Pricing: the Free plan includes 1,000 branded links total, 5 custom domains and 50,000 tracked clicks a month. Its comparison table lists Hobby at $5/month, Pro at $18/month and Team at $48/month.

A small release workflow

Here is a pattern that works with any of the four:

Write the release post in your repo.
Ask the agent: "Create a short link for each external URL in posts/v2-release.md, use slugs that start with v2-, and replace the long URLs in the file."
Review the diff before committing. The agent can pick the wrong URL, so check every replacement.
A week later: "Get stats for every link with a v2- slug and summarize clicks by link."

Step 3 matters. An agent with write access to your shortener can create links you did not intend, and with Bitly, Dub or Short.io those links can sit on your branded domain. Review before you publish.

Which one to pick

You already pay for Bitly, Dub or Short.io: use that vendor's server. Your existing domains and analytics come with it.
You need branded domains on a budget: Short.io's or Dub's free plans.
You want link tracking plus other marketing tools in one MCP server and do not need a custom domain: Appie.

FAQ

Do I need a paid plan to use these MCP servers?
Appie, Dub and Short.io offer free plans with API access. Bitly says its MCP server is available with some paid plans.

Can the agent post the link anywhere?
No. These servers create and read links. Publishing the post is still your step.

Are clicks from bots counted?
Each vendor filters differently, and none of the docs we read gives a full method. Treat small click counts with caution.

RG, Founder, Appie.run

Build and Train a Website Chatbot From Claude Code or Cursor (MCP Walkthrough)

appierun — Thu, 29 Oct 2026 15:57:11 +0000

You can create a support chatbot, train it on your sitemap, and test its answers without leaving your editor. The loop is five tool calls: create_chatbot, add_chatbot_content, chatbot_status, ask_chatbot, and list_chatbots when you come back later. This walkthrough uses Appie.run's MCP server, with every tool name, argument and credit cost taken from appie.run/docs/mcp on 28 Oct 2026.

Disclosure: Appie.run publishes this post, and the server used here is ours.

This is the third walkthrough in the series, after Reddit threads and reply drafts and LinkedIn profiles and leads. If you've done either, skip to Step 3.

What you need

An Appie project. The Free plan has 500 credits and needs no credit card.
A project API key that starts with esk_.
Cursor, Claude Code, or another MCP client that supports remote servers with custom headers.
A public sitemap, or a few pages of text you want the bot to answer from.

Step 1: Create the key

In Appie, open the project and go to API in the sidebar. A project admin generates one esk_ key. Two things worth knowing:

The same key is used by Event Store. Regenerating it stops both immediately.
The key has no balance of its own. Paid calls run on the project's credits, then the project owner's. Every tool result includes credits_remaining.

export APPIE_API_KEY=esk_YOUR_KEY

Keep it out of git.

Step 2: Add the server

Cursor. From Appie's docs:

{
  "mcpServers": {
    "appie": {
      "url": "https://appie.run/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Code.

claude mcp add --transport http appie https://appie.run/mcp \
  --header "Authorization: Bearer $APPIE_API_KEY"

Run claude mcp list to check the connection. A request with a placeholder key returned HTTP 401 when we tried it on 28 Oct 2026, which is the expected response for a bad key.

Step 3: Find the sitemap you'll train on

The bot learns fastest from a sitemap, because one call pulls in every page it lists. If you don't know where your sitemap lives, Appie's free Sitemap Finder and Checker reads your robots.txt Sitemap: lines and the usual paths (including the WordPress path) and reports which files load and how many URLs they list.

A tip before you train: a sitemap often includes pages you don't want a support bot quoting, such as old blog posts, legal archives or job ads. If yours is noisy, train on a smaller sitemap file or on specific URLs instead.

Step 4: Create the bot

Ask your agent: "Create an Appie chatbot called Support Bot for example.com with a short system prompt."

The agent calls create_chatbot. name is required. Optional fields are system_prompt, openai_model (gpt-4o-mini, gpt-4o or gpt-3.5-turbo) and temperature from 0 to 1. Creation is free. Illustrative arguments:

{
  "name": "Support Bot",
  "system_prompt": "Answer questions about Example Co using only the provided content. If the answer is not in the content, say you don't know and suggest emailing support.",
  "openai_model": "gpt-4o-mini",
  "temperature": 0.2
}

A low temperature keeps answers close to your content. Note the returned chatbot_id; every later call needs it.

Step 5: Add knowledge

Call add_chatbot_content with one of these content_type values:

sitemap: Fields: url (http or https); Use it for: A whole site or section
url: Fields: url (http or https); Use it for: One page, such as pricing or a returns policy
text: Fields: title, content; Use it for: Facts that aren't on the site yet
article: Fields: article_id; Use it for: An article from Appie's Content Writer in the same project

Illustrative calls:

{ "chatbot_id": "YOUR_BOT_ID", "content_type": "sitemap", "url": "https://www.example.com/sitemap.xml" }

{
  "chatbot_id": "YOUR_BOT_ID",
  "content_type": "text",
  "title": "Support hours",
  "content": "Support replies Monday to Friday, 9am to 6pm CET. Email support@example.com."
}

The text type is handy for the questions your site never answers clearly: support hours, refund windows, which plan includes what.

Step 6: Wait for training

Processing runs in the background. Call chatbot_status with the chatbot_id to read the bot's training status and its recent sources. It's free, so poll it as often as you like. A prompt that works well:

"Check chatbot_status for YOUR_BOT_ID every 30 seconds until training finishes, then list the sources it added."

Step 7: Test it before customers do

ask_chatbot sends a message to a chatbot_id and returns a reply. It costs 1 credit per call. Pass the session_id from a previous reply to continue the same conversation, which lets you test follow-up questions.

Write a short test set and have your agent run it:

Three questions the site answers clearly (pricing, a feature, a policy).
Two questions it answers only in passing.
Two questions it doesn't answer at all. The bot should say it doesn't know, not guess.
One follow-up in the same session ("And for the annual plan?").

Ten questions cost 10 credits. If an answer is wrong, the fix is usually the content, not the prompt: add a text source with the correct fact, wait for chatbot_status, and ask again.

Step 8: Put it on your site

The MCP tools cover building, training and testing. To go live, open the chatbot in the Appie dashboard. Per appie.run/ai-chatbots, you embed it with a script tag (or the Shopify app embed), and the dashboard adds lead capture, CSV export and webhooks, and analytics.

Prompts to paste

"List my Appie chatbots and their training status."
"Create a chatbot for example.com, train it on https://www.example.com/sitemap.xml, and tell me when training is done."
"Add a text source titled Refund policy with this content: ..."
"Ask the bot these eight questions, one by one, and give me a table of question, reply, and whether the reply is supported by our site."
"Show credits_remaining after each paid call."

What it costs

list_chatbots: Credits (as of 28 Oct 2026): 0
create_chatbot: Credits (as of 28 Oct 2026): 0
add_chatbot_content: Credits (as of 28 Oct 2026): No cost stated in the docs
chatbot_status: Credits (as of 28 Oct 2026): 0
ask_chatbot: Credits (as of 28 Oct 2026): 1 per message

Building a bot is free on the pricing page too; conversations use chatbot query credits. Paid plans are Starter at $19 a month (2,000 credits) and Standard at $49 a month (5,000 credits), per appie.run/pricing.

Troubleshooting

HTTP 401. The key is missing, wrong, or was regenerated.
app_not_allowed. The person who generated the key can't use the chatbots app in that project. A project owner can use every app.
insufficient_credits. The response includes required and available.
not_found. The bot or article ID belongs to another project.
Answers ignore a page. Check chatbot_status to confirm the source was added, then ask about that page directly.

Errors come back as an MCP tool error whose text is JSON with error and message, so your agent can read and explain them.

The same actions are also available as an HTTP API and CLI; see appie.run/docs/mcp. The repo is on GitHub.

RG, Founder, Appie.run

How to Generate an XML Sitemap for a Static Site With Python (Skip noindex Pages, Split at 50,000 URLs)

appierun — Wed, 28 Oct 2026 15:51:20 +0000

Most static site generators can produce a sitemap, but the default output often includes pages you don't want indexed: drafts marked noindex, duplicate pages that point a canonical elsewhere, and a lastmod on every URL set to the moment the build ran. This post walks through a small Python script that builds sitemap.xml from your build folder and avoids those three problems.

Disclosure: Appie.run publishes this post. Appie has a free XML Sitemap Generator, mentioned near the end. The script below has no dependency on it. Facts about the sitemap format come from sitemaps.org and Google Search Central, read on 28 Oct 2026.

If you want to check an existing sitemap rather than build one, our earlier post How to validate an XML sitemap covers the common errors.

The rules the script follows

From the sitemaps protocol and Google's Build and submit a sitemap page:

Size limits. One sitemap holds at most 50,000 URLs or 50MB uncompressed. Past that, split it into several files and list them in a sitemap index.
UTF-8 and escaping. The file must be UTF-8. Tag values must be entity-escaped, and URLs must be URL-escaped.
Absolute URLs. Use https://www.example.com/page.html, not /page.html.
Canonical URLs only. List the URLs you want in search results.
priority and changefreq. Google says it ignores both. The script leaves them out.
lastmod. Google uses it only if it's consistently and verifiably accurate, and it should reflect the last significant change to the page. A build timestamp on every page fails that test, so the script either uses a real date or omits the tag.
Location. Unless you submit through Search Console, a sitemap only affects URLs under its own directory. Put it at the site root.

The script

Save this as gen_sitemap.py. It uses only the standard library (Python 3.8+).

#!/usr/bin/env python3
"""Build sitemap.xml from a static site's output folder (dist/, public/, _site/)."""
import argparse, datetime, re, subprocess
from pathlib import Path
from urllib.parse import quote
from xml.sax.saxutils import escape

MAX_URLS = 50_000  # per sitemap file, per the sitemaps protocol

NOINDEX = re.compile(r'<meta[^>]+name=["\']robots["\'][^>]+content=["\'][^"\']*noindex', re.I)
CANONICAL = re.compile(r'<link[^>]+rel=["\']canonical["\'][^>]+href=["\']([^"\']+)["\']', re.I)


def page_url(base, root, path):
    rel = path.relative_to(root).as_posix()
    if rel == "index.html":
        rel = ""
    elif rel.endswith("/index.html"):
        rel = rel[: -len("index.html")]  # keep trailing slash
    return base.rstrip("/") + "/" + quote(rel)  # percent-encode spaces, non-ASCII


def last_modified(path, root, src_root):
    """Last git commit date of the matching source file, else None.

    Build output mtimes are all "now", which makes lastmod useless, so we
    only trust git history for a file at the same relative path in --src.
    """
    if src_root:
        src_file = src_root / path.relative_to(root)
        if not src_file.exists():
            return None
        try:
            out = subprocess.run(
                ["git", "log", "-1", "--format=%cs", "--", path.relative_to(root).as_posix()],
                cwd=src_root, capture_output=True, text=True, check=True,
            ).stdout.strip()
            if out:
                return out
        except (subprocess.CalledProcessError, FileNotFoundError):
            pass
    return None


def collect(root, base, src_root):
    entries, skipped = [], []
    for path in sorted(root.rglob("*.html")):
        if path.name == "404.html":
            continue
        url = page_url(base, root, path)
        html = path.read_text(encoding="utf-8", errors="ignore")
        if NOINDEX.search(html):
            skipped.append((url, "noindex"))
            continue
        m = CANONICAL.search(html)
        if m and m.group(1).rstrip("/") != url.rstrip("/"):
            skipped.append((url, "canonical points to " + m.group(1)))
            continue
        entries.append((url, last_modified(path, root, src_root)))
    return entries, skipped


def write_urlset(entries, out):
    lines = ['<?xml version="1.0" encoding="UTF-8"?>',
             '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">']
    for url, lastmod in entries:
        tag = f"<lastmod>{lastmod}</lastmod>" if lastmod else ""
        lines.append(f"  <url><loc>{escape(url)}</loc>{tag}</url>")
    lines.append("</urlset>")
    out.write_text("\n".join(lines) + "\n", encoding="utf-8")


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("root", type=Path, help="built site folder, e.g. dist")
    ap.add_argument("--base", required=True, help="https://www.example.com")
    ap.add_argument("--src", type=Path, help="git checkout whose files mirror the output paths")
    args = ap.parse_args()

    entries, skipped = collect(args.root, args.base, args.src)
    for url, why in skipped:
        print(f"skipped {url}: {why}")

    chunks = [entries[i:i + MAX_URLS] for i in range(0, len(entries), MAX_URLS)] or [[]]
    if len(chunks) == 1:
        write_urlset(chunks[0], args.root / "sitemap.xml")
        print(f"wrote sitemap.xml with {len(entries)} URLs")
        return
    names = []
    for n, chunk in enumerate(chunks, 1):
        name = f"sitemap-{n}.xml"
        write_urlset(chunk, args.root / name)
        names.append(name)
    today = datetime.date.today().isoformat()
    index = ['<?xml version="1.0" encoding="UTF-8"?>',
             '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">']
    for name in names:
        loc = escape(args.base.rstrip("/") + "/" + name)
        index.append(f"  <sitemap><loc>{loc}</loc><lastmod>{today}</lastmod></sitemap>")
    index.append("</sitemapindex>")
    (args.root / "sitemap.xml").write_text("\n".join(index) + "\n", encoding="utf-8")
    print(f"wrote sitemap index with {len(names)} files, {len(entries)} URLs")


if __name__ == "__main__":
    main()

What each part does

page_url maps a file path to a URL. index.html becomes the folder URL with a trailing slash, so dist/blog/a-post/index.html becomes https://www.example.com/blog/a-post/. Paths are percent-encoded, so my page.html becomes my%20page.html.

collect walks every .html file and skips three kinds of page:

404.html
pages with a robots meta tag containing noindex
pages whose rel="canonical" points to a different URL

Each skip is printed, so you can see why a page is missing.

last_modified is the part most generators get wrong. Files in a build folder all have the build time as their modified date, which makes every lastmod identical and meaningless. The script only sets lastmod when you pass --src with a git checkout whose files sit at the same relative paths as the output (true for hand-written HTML sites, often not true for generators that render Markdown). It then uses the date of the last commit touching that file. Otherwise it leaves lastmod out, which is valid.

write_urlset escapes each URL with xml.sax.saxutils.escape, so an & in a query string becomes &.

main writes one sitemap.xml when you have 50,000 URLs or fewer. Above that it writes sitemap-1.xml, sitemap-2.xml and so on, and makes sitemap.xml a sitemap index pointing to them.

Run it

# after your build step
python3 gen_sitemap.py dist --base https://www.example.com

# with lastmod from git, for a site whose source paths match the output
python3 gen_sitemap.py dist --base https://www.example.com --src .

On a small test folder, the output looked like this:

skipped https://www.example.com/about-copy.html: canonical points to https://www.example.com/about.html
skipped https://www.example.com/drafts/x.html: noindex
wrote sitemap.xml with 5 URLs

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url><loc>https://www.example.com/about.html</loc></url>
  <url><loc>https://www.example.com/blog/a-post/</loc></url>
  <url><loc>https://www.example.com/</loc></url>
  <url><loc>https://www.example.com/my%20page.html</loc></url>
  <url><loc>https://www.example.com/tom%26jerry.html</loc></url>
</urlset>

To test the split, change MAX_URLS to 2 in a copy of the script. On the same folder it wrote three files plus an index.

Add it to your build

In a package.json:

{
  "scripts": {
    "build": "astro build && python3 gen_sitemap.py dist --base https://www.example.com"
  }
}

Or as a CI step after the build, before deploy. Then add one line to robots.txt so crawlers find it:

Sitemap: https://www.example.com/sitemap.xml

Google's docs list three ways to submit: Search Console, the Search Console API, or the Sitemap: line in robots.txt.

Known limits

Regex HTML parsing. The noindex and canonical checks expect the attributes in the usual order (name before content, rel before href). If your templates write them the other way round, swap in html.parser from the standard library.
No 50MB check. At 50,000 short URLs you'll be well under 50MB, but if your URLs are very long, check the file size too.
Only HTML. PDFs and other files you want indexed need adding by hand.
Trailing slashes. The canonical comparison ignores a trailing slash. If your site treats /page and /page/ as different pages, tighten that check.

When a script is more than you need

If you just need a one-off sitemap for a small site, a hosted tool is quicker:

Appie's free XML Sitemap Generator crawls a public site for up to 80 pages, or takes a pasted list of up to 50,000 URLs, and returns sitemap XML. A single free run stops at 80 HTML pages or after 12 seconds, so paste a URL list for larger sites. It asks you to choose changefreq and priority; since Google ignores both, any value is fine. There's a captcha before each run.
Screaming Frog SEO Spider is a desktop crawler that can generate XML sitemaps. Per its site on 28 Oct 2026, it crawls 500 URLs for free, and a licence to remove the limit is £199 per year.

After generating, run the file through a validator such as Appie's free XML Sitemap Validator, which checks the root element, absolute URLs, lastmod, duplicates and the 50,000 URL limit.

RG, Founder, Appie.run

How to Write a Website FAQ That AI Answers Can Quote (Now That Google's FAQ Rich Results Are Gone)

appierun — Tue, 27 Oct 2026 15:50:42 +0000

For years the main reason to add an FAQ section was the dropdown it could earn in Google results. That reason has gone. The page itself still matters, though, because AI assistants and AI search features pull short, direct answers from pages, and a well-built FAQ is one of the easiest things on a site for them to lift.

This post covers what changed at Google, what still makes an FAQ worth writing, and the HTML pattern we use so each answer stands on its own.

Disclosure: Appie.run publishes this post. The AI FAQ Generator and Website FAQ Generator mentioned below are our free tools. Everything else here works with any CMS and no tool at all.

What Google changed (as read on 26 Oct 2026)

From Google's Search Central updates and Search Console Help:

FAQ rich results stopped appearing in Google Search on 7 May 2026, and Google added a deprecation notice on 8 May.
On 15 June 2026 Google removed the FAQ structured data documentation, the FAQ report in Search Console and FAQ support in the Rich Results Test.
Search Console API support for FAQ appearance data was removed in August 2026.
Google says existing FAQPage markup can stay on your pages and causes no harm.
In the same June update Google noted that an llms.txt file isn't needed for Google Search.

So: no more SERP dropdown, no penalty for leftover markup, and no special file required. What's left is the content.

Why an FAQ is still worth writing

Nobody outside the AI companies can tell you exactly how each assistant picks its sources, and we won't pretend to. What you can control is whether your answer is easy to find, easy to extract and correct when pulled out of context. A question-and-answer block does all three if you write it properly:

The question matches the way people actually ask it.
The first sentence of the answer is the answer.
The answer makes sense without the paragraphs around it.

Those same properties help a human who lands on the page from a support link, so the work isn't wasted whichever way the traffic arrives.

Step 1: Collect real questions

Don't invent questions in a meeting. Pull them from places where customers already asked:

Support tickets and live chat transcripts
Sales call notes ("Does it work with...?", "What happens when...?")
Reddit and community threads in your category
Your site search logs

Group duplicates, then keep the 8 to 15 that come up most or block a purchase.

Step 2: Write answers that survive being quoted alone

A quick test for each answer: paste it into a blank doc with only the question above it. Does it still make sense?

Weak:

Yes, as mentioned above, it does, depending on your plan.

Better:

Yes. Team plans include SSO via SAML. The Starter plan does not.

Rules we follow:

Answer in the first sentence. Yes/no, a number, or a name.
Name the thing. Say "the Starter plan", not "this plan".
Keep it to 40 to 80 words for most answers. Link out for detail.
Date anything that changes. "As of 26 Oct 2026, the Starter plan costs $19/month." Prices and limits go stale, and a stale quoted answer is worse than none.
Only state what the page can back up. If the policy lives elsewhere, link to it rather than paraphrasing it loosely.

Step 3: Use plain, semantic HTML

You don't need a plugin. Headings for questions and paragraphs for answers are enough, and they render the same for every crawler:

<section id="faq" aria-labelledby="faq-title">
  <h2 id="faq-title">Frequently asked questions</h2>

  <h3 id="faq-sso">Does the Starter plan include SSO?</h3>
  <p>No. SSO via SAML is included on Team plans only. The Starter plan
     uses email and password sign-in. <a href="/pricing">Compare plans</a>.</p>

  <h3 id="faq-cancel">Can I cancel at any time?</h3>
  <p>Yes. You can cancel from the Billing page, and your plan stays active
     until the end of the current billing period.</p>
</section>

If you prefer collapsible answers, <details>/<summary> keeps the text in the HTML:

<details>
  <summary>Can I cancel at any time?</summary>
  <p>Yes. You can cancel from the Billing page, and your plan stays active
     until the end of the current billing period.</p>
</details>

Avoid loading answers only via JavaScript after a click. If the text isn't in the served HTML, some crawlers will never see it.

Give each question an id so you can link straight to it from support replies and docs.

Step 4: Keep or add FAQPage markup (optional)

Google no longer shows FAQ rich results, and it says leftover markup does no harm. Other consumers of schema.org data may still read it, so if it's already there, keep it in sync with the visible text. If you add it, mirror the on-page wording exactly:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Can I cancel at any time?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes. You can cancel from the Billing page, and your plan stays active until the end of the current billing period."
      }
    }
  ]
}
</script>

The risk with markup is drift: someone updates the visible answer and forgets the JSON. If your FAQ comes from a CMS field, generate both from the same source.

Step 5: Put the FAQ where the question is asked

One giant /faq page is fine as an index, but the most useful placement is next to the thing in question: pricing questions on the pricing page, setup questions in the docs. A short block of 4 to 6 questions per page tends to stay accurate because the owner of that page sees it.

Step 6: Review it on a schedule

Add a "last reviewed" date and put a recurring reminder on someone's calendar. Every price, limit and integration claim in the FAQ should be checked against the product at least each quarter.

Getting a first draft faster

If you have the source material but not the time, two of our free browser tools can produce a draft for you to edit (both run a captcha check first):

AI FAQ Generator (appie.run/tools/ai-faq-generator): paste up to 2,000 characters of text, pick 1 to 10 FAQs, a language and a tone. The answers are grounded in the text you pasted, and it doesn't add policies or prices that aren't there.
Website FAQ Generator (appie.run/tools/website-faq-generator): give it up to 5 public URLs. It skips questions it can't answer from those pages instead of guessing.

Treat the output as a draft. Check every answer against Step 2's rules before it goes live.

Checklist

[ ] Questions come from real customer sources
[ ] Each answer starts with the answer
[ ] Each answer makes sense on its own
[ ] Prices and limits carry an "as of" date
[ ] Questions and answers are in the served HTML
[ ] Any FAQPage JSON-LD matches the visible text word for word
[ ] A review date is set

Google sources: Search Central blog and Search Console Help pages on FAQ rich results and structured data, read 26 Oct 2026.

RG, Founder, Appie.run

How to Convert Notion to Markdown (Export, Public Pages and the API), With a Cleanup Script

appierun — Mon, 26 Oct 2026 15:54:40 +0000

You wrote the docs in Notion. Now you want them as .md files: for a docs site, for a Git repo, or for an LLM pipeline that reads Markdown far more happily than it reads a Notion URL. There are three practical ways to get there, and each one fits a different situation:

Notion's built-in "Markdown & CSV" export, for private pages and whole page trees.
A public-page converter in the browser, for a page that's already published.
The Notion API with notion-to-md, for repeatable, scripted conversion.

The built-in export is the most common route, and it leaves a few rough edges, so this post also includes a small Python script that tidies the export folder.

Disclosure: Appie.run publishes this post, and the public-page converter in Method 2 is our free tool. Methods 1 and 3 don't need anything from us.

Notion behaviour below is from Notion's Help Center and developer docs as read on 25 Oct 2026. Notion changes its menus from time to time, so check the linked pages if a label doesn't match.

Which method should you use?

Built-in export: Needs an account or token: Notion account with access to the page; Private pages: Yes; Subpages and databases: Subpages as separate files; databases as CSV plus a .md per row; Best for: One-off exports, backups, migrating a wiki
Public-page converter: Needs an account or token: The page must be published to the web; Private pages: No; Subpages and databases: The published page's text; Best for: Quick copy of a page that's already public
API + notion-to-md: Needs an account or token: Notion API token; Private pages: Yes, if the token can see the page; Subpages and databases: Child pages returned as separate strings; Best for: Docs pipelines, scheduled syncs, CI

If you only need to do this once, start with Method 1. If you'll do it every week, go straight to Method 3.

Method 1: Notion's built-in Markdown & CSV export

According to Notion's export guide, any non-database page can be exported as a Markdown file. Full-page databases export as a CSV file, with a Markdown file for each subpage.

On desktop:

Open the page and click the ••• menu at the top right.
Click Export.
Choose Markdown & CSV from the format dropdown.
Switch on Include subpages if you want the pages nested under this one.
Click Export. You get a zip file with the Markdown and CSV files.

Mobile works the same way: •••, then Export, then pick Markdown & CSV under Export format. Notion also emails you a download link. For very large exports, Notion says it may email a link rather than start the download straight away.

Whole workspace. Notion's guide lists Settings > Workspace > General > Export all workspace content. The download link arrives by email (or in your Notion inbox if email notifications are off), expires after 7 days, and Notion says the export can take up to 30 hours for large workspaces. Pages the exporter can't access, such as other people's private pages, are left out. There's also a beta admin API for starting workspace exports on the Enterprise Plan.

No Export option? On Enterprise workspaces, an owner can disable exporting. Guests need Full access to a page to export it.

Clean up the export

Unzip the export and open a file. The content is fine, but a few things get in the way of using it in a repo or docs site:

File and folder names often carry a long ID after the page title, for example Team Wiki 1a2b3c4d5e6f708192a3b4c5d6e7f809.md. Links between pages point at those names, URL-encoded.
Callouts come out as HTML. Notion's guide says callout blocks are exported as HTML because Markdown has no equivalent. Static site generators and Markdown linters may not render that the way you want.

Here's a script that strips the ID suffix from file and folder names, rewrites relative links to match, and turns callouts into blockquotes. It only uses the Python standard library.

"""Tidy a Notion "Markdown & CSV" export: strip ID suffixes, fix links, convert callouts."""
import re
import sys
import pathlib
import urllib.parse

ID = re.compile(r" [0-9a-f]{32}")  # " <32 hex chars>" after the page title
root = pathlib.Path(sys.argv[1])

# 1. Rename files and folders, deepest paths first so parents rename last.
for p in sorted(root.rglob("*"), key=lambda p: -len(p.parts)):
    new = p.with_name(ID.sub("", p.name))
    if new == p:
        continue
    if new.exists():
        print(f"skip (name taken): {p}")
        continue
    p.rename(new)

def fix_link(m):
    target = m.group(1)
    if "://" in target or target.startswith(("#", "mailto:")):
        return m.group(0)  # leave external links and anchors alone
    path, _, anchor = target.partition("#")
    path = urllib.parse.quote(ID.sub("", urllib.parse.unquote(path)))
    return "](" + path + ("#" + anchor if anchor else "") + ")"

def fix_callout(m):
    lines = m.group(1).strip().splitlines()
    return "\n".join("> " + line if line.strip() else ">" for line in lines)

# 2. Rewrite relative links and turn <aside> callouts into blockquotes.
for md in root.rglob("*.md"):
    text = md.read_text(encoding="utf-8")
    text = re.sub(r"\]\(([^)\s]+)\)", fix_link, text)
    text = re.sub(r"<aside>(.*?)</aside>", fix_callout, text, flags=re.S)
    md.write_text(text, encoding="utf-8")
    print(f"cleaned: {md.relative_to(root)}")

Run it on a copy of the unzipped folder, since it renames files in place:

cp -r "Export-folder" notion-md
python3 clean_notion_export.py notion-md

We ran it with Python 3.13 on a small sample export we built by hand to mimic Notion's format, not a real Notion export: a parent page, a subpage, a database CSV and an image, all with ID suffixes, plus an external link and a two-line callout. Before:

Start with [Onboarding](Team%20Wiki%201a2b3c4d5e6f708192a3b4c5d6e7f809/Onboarding%200f1e2d3c4b5a69788796a5b4c3d2e1f0.md).

See our [site](https://example.com/docs?a=1&b=2#top).

<aside>
💡 Callout text
Second line of the callout.

</aside>

After:

Start with [Onboarding](Team%20Wiki/Onboarding.md).

See our [site](https://example.com/docs?a=1&b=2#top).

> 💡 Callout text
> Second line of the callout.

Every relative link in the sample still resolved to a real file after the rename, and the external URL was left untouched.

Two things to check on your own export before you trust the script:

The ID pattern. The script expects a space followed by 32 lowercase hex characters. Open your zip and compare. If your names look different, change the ID regex.
The callout HTML. The script assumes callouts are wrapped in <aside> tags. Open one exported callout in a text editor; if Notion used different markup, change the second re.sub pattern.

The script also skips a rename when the clean name is already taken (two sibling pages with the same title, for example), so nothing gets overwritten. Fix those by hand.

Method 2: Convert a public Notion page in the browser

If the page is already published, you don't need an export at all. Our free Convert Notion to Markdown tool takes a public notion.so or notion.site URL and converts the published text to Markdown.

Paste the public URL.
Complete the captcha (Cloudflare Turnstile, one check per run).
Copy the Markdown or download it.

The limit is in the name: it reads what the public page exposes. A private Notion URL doesn't expose any text to read, so for private pages you'd either publish the page first or use Method 1 or 3. It also works on one page at a time, so for a tree of subpages the built-in export is the better fit.

Method 3: Use the Notion API with notion-to-md

For anything you'll repeat, such as syncing a docs space into a repo every night, use the API. notion-to-md is an open-source package that turns Notion blocks into Markdown. As of 25 Oct 2026, the latest version on npm is 3.1.9 (a 4.0 alpha is also published; the code below is for 3.x).

1. Get a token. Notion's developer docs describe two simple options:

A personal access token, created in the Developer portal, which acts as you and uses your permissions. Notion notes that on Business and Enterprise plans, creating one may need a workspace owner to enable it.
An internal connection token, for team-owned automations. Notion says the page must be shared with the connection first: open the page, click •••, choose Add connections, and pick your connection. Without that, API requests return an error.

Keep the token in an environment variable, not in your code.

2. Install the packages.

npm install notion-to-md @notionhq/client

3. Convert a page. This follows the package README:

// convert.js
const { Client } = require("@notionhq/client");
const { NotionToMarkdown } = require("notion-to-md");
const fs = require("fs");

const notion = new Client({ auth: process.env.NOTION_API_KEY });
const n2m = new NotionToMarkdown({ notionClient: notion });

(async () => {
  const pageId = process.argv[2]; // the page ID, taken from the page URL
  const mdblocks = await n2m.pageToMarkdown(pageId);
  const mdString = n2m.toMarkdownString(mdblocks);
  fs.writeFileSync("page.md", mdString.parent);
  console.log("Wrote page.md");
})();

NOTION_API_KEY=your_token node convert.js <page-id>

toMarkdownString returns an object. The page itself is in .parent. Since v2.7.0 the package doesn't write child pages to disk for you; it returns their Markdown in the same object, so loop over it and save them yourself if you need them.

We checked the method names against version 3.1.9 by running the script above with a stubbed Notion client that returned a heading, paragraph, bullet, to-do and callout. Output:

# Team Wiki

Hello from Notion.

- First point

> 💡 Callout text

- [x] Ship docs

Note that notion-to-md rendered the callout as a blockquote, so API output doesn't need the callout fix from the cleanup script. Run it against one real page of yours before wiring it into CI, since a stub can't catch permission errors.

Gotchas

Callouts are HTML in the export. Covered above. The API route with notion-to-md gave us blockquotes instead.

Databases come out as CSV. A full-page database exports as a CSV plus one Markdown file per row (subpage). If you want the table itself in Markdown, convert the CSV. Our free CSV to Markdown tool takes the first row as the header and returns a Markdown table. Notion also notes you can export only the current view or the default view of a database, not all views at once.

Windows and long paths. Notion's guide says Windows may fail to open the zip when nested folder and file names pass the 260-character path limit. Its suggested fixes: uncheck Create folders for subpages when exporting, or extract with 7-Zip. The cleanup script shortens names too, but only after you've extracted the files.

Images and attachments. Check where the image files landed and whether the image links still resolve after you move the folder. The cleanup script rewrites relative image links along with page links.

Private pages. The public-URL converter can't see them. Use the export or the API.

Using the Markdown for RAG or a chatbot

Clean Markdown from Notion makes a decent knowledge source because headings survive, and headings are natural split points. For chunking and what to strip before indexing, see our guide on converting PDFs to Markdown for RAG; the same advice applies here.

To turn a published Notion FAQ or help page into question-and-answer pairs, our free Notion to FAQ Generator writes FAQs from a public Notion URL, and it's instructed to skip questions the page can't answer. For the full setup of a site chatbot on your docs, see How to set up an AI chatbot for your website FAQ.

FAQ

Can Notion export to Markdown?
Yes. Use ••• > Export and choose Markdown & CSV. Non-database pages export as Markdown; full-page databases export as CSV with a Markdown file per subpage.

Why are my Notion callouts HTML after export?
Notion exports callouts as HTML because Markdown has no equivalent. The cleanup script above turns <aside> callouts into blockquotes.

How do I convert a Notion database to Markdown?
It exports as a CSV plus a .md file for each subpage. Convert the CSV into a Markdown table with a script or a CSV-to-Markdown converter.

Can I convert a private Notion page without exporting?
Not with a public-URL converter, since a private page exposes no text. Use the built-in export or the API with a token that can see the page.

Does notion-to-md need the page to be shared?
With an internal connection token, yes: add the connection to the page via ••• > Add connections. A personal access token acts as you and uses your own permissions.

Got a public Notion page? Paste the URL into our free converter and copy the Markdown: appie.run/tools/convert-notion-to-markdown. To turn those docs into a site chatbot, Appie's AI Chatbots start on the Free plan (500 credits, no credit card needed).

If you use the AI agent and approval patterns from our earlier post, how to add human approval to AI agent actions, a Notion-to-Markdown sync is a good low-risk job to automate first: it reads, it doesn't write back.

How to Validate an XML Sitemap: Common Errors, What Google Ignores, and a Small Python Checker

appierun — Sun, 25 Oct 2026 15:51:07 +0000

Sitemaps are one of those files nobody looks at until something breaks. A deploy changes the URL structure, a plugin starts emitting relative paths, a query string sneaks in an unescaped &, and the sitemap quietly stops parsing. Search Console tells you eventually. A check in CI tells you before you ship.

This post covers what the sitemap protocol actually requires, which fields Google says it ignores, the errors that show up most often in real sitemaps, and a small Python script you can drop into a pipeline. Everything protocol-related below is from sitemaps.org and Google's Build and submit a sitemap page, as read on 24 Oct 2026.

Disclosure: Appie.run publishes this post. We mention our free sitemap tools near the end as an option if you'd rather not run a script; the code here works without them.

What the protocol requires

A minimal valid sitemap looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://www.example.com/foo.html</loc>
    <lastmod>2026-10-20</lastmod>
  </url>
</urlset>

The rules worth encoding in a checker:

Root element. Either <urlset> (a list of pages) or <sitemapindex> (a list of sitemaps), in the http://www.sitemaps.org/schemas/sitemap/0.9 namespace.
Encoding. The file must be UTF-8.
Size. No more than 50,000 URLs and no larger than 50MB (52,428,800 bytes) uncompressed per file. A sitemap index has the same limits for the number of sitemaps it lists.
<loc>. Required. Google asks for fully qualified, absolute URLs, and sitemaps.org says the value must be less than 2,048 characters.
Escaping. All values must be entity-escaped, so & becomes &, and URLs must be URL-escaped.
<lastmod>. Optional, in W3C Datetime format: 2026-10-20 or 2026-10-20T10:00:00+00:00, for example.
<changefreq>. Optional, one of always, hourly, daily, weekly, monthly, yearly, never.
<priority>. Optional, from 0.0 to 1.0.
One host. sitemaps.org says all URLs in a sitemap must be from a single host, and that a sitemap's location limits which URLs it can include: a file at /catalog/sitemap.xml can list URLs under /catalog/, not the rest of the site.

What Google says it ignores (and what it uses)

This changes how much effort the optional fields deserve. Google's documentation says:

Google ignores <priority> and <changefreq>.
Google uses <lastmod> if it's consistently and verifiably accurate, for example when it matches the page's real last modification. Google says it should reflect the last significant update (main content, structured data, links), and that a copyright date change doesn't count.
Sitemaps should list the URLs you want to see in search results, which in practice means canonical URLs.
A sitemap at the site root can affect all files on the site, which is where Google recommends putting it. Placed elsewhere, it only affects descendants of its directory unless you submit it through Search Console.

The practical takeaway: don't spend time tuning priority values. Spend it making lastmod honest. A generator that stamps every URL with today's date on every build is telling Google nothing useful.

Other search engines may treat these fields differently, so keeping priority and changefreq valid costs nothing. Just don't expect them to move anything on Google.

The errors we see most

These are the problems that come up again and again when people paste sitemaps into a validator.

1. Relative URLs

<url><loc>/pricing</loc></url>

Usually a templating bug: the generator uses the path where it should use the full URL. Fix it with the absolute URL, including scheme and host.

2. Unescaped ampersands

<loc>https://example.com/search?q=shoes&page=2</loc>

This breaks the XML parser, which means the entire file fails, not one entry. It must be &. If your sitemap is built with string concatenation instead of an XML library, this is the bug waiting to happen.

3. Invalid lastmod

<lastmod>20/10/2026</lastmod>
<lastmod>Oct 20, 2026</lastmod>

Both are invalid. Use YYYY-MM-DD or a full timestamp with a timezone.

4. Out-of-range priority or made-up changefreq

<priority>2</priority>
<changefreq>often</changefreq>

Google ignores both fields, but invalid values are still protocol errors and some tools will flag the file.

5. Duplicates and mixed hosts

The same URL listed twice, or a mix of example.com and www.example.com. Duplicates are harmless but noisy. Mixed hosts usually mean your canonical setup and your sitemap disagree, and that's worth fixing at the source.

6. Too big for one file

A growing catalogue crosses 50,000 URLs and nobody splits the file. Split it into several sitemaps and list them in a sitemap index.

7. Listing URLs you don't want indexed

Redirects, 404s, noindex pages and non-canonical variants. These aren't XML errors, so a schema check won't catch them. You need to request the URLs (see the optional step below).

A small Python checker

This script uses only the standard library. It takes a file path or a URL, checks the rules above, prints errors and warnings, and exits non-zero on errors so it can fail a CI job.

import sys
import urllib.request
from datetime import datetime
from urllib.parse import urlparse
import xml.etree.ElementTree as ET

NS = "{http://www.sitemaps.org/schemas/sitemap/0.9}"
MAX_URLS = 50_000
MAX_BYTES = 52_428_800  # 50MB uncompressed


def load(source):
    if source.startswith(("http://", "https://")):
        req = urllib.request.Request(source, headers={"User-Agent": "sitemap-check/1.0"})
        with urllib.request.urlopen(req, timeout=30) as resp:
            return resp.read()
    with open(source, "rb") as f:
        return f.read()


def valid_w3c_date(value):
    for fmt in ("%Y", "%Y-%m", "%Y-%m-%d", "%Y-%m-%dT%H:%M:%S%z", "%Y-%m-%dT%H:%M%z", "%Y-%m-%dT%H:%M:%S.%f%z"):
        try:
            datetime.strptime(value.replace("Z", "+00:00"), fmt)
            return True
        except ValueError:
            pass
    return False


def check(source):
    raw = load(source)
    errors, warnings = [], []

    if len(raw) > MAX_BYTES:
        errors.append(f"File is {len(raw):,} bytes; the limit is {MAX_BYTES:,} uncompressed")
    try:
        raw.decode("utf-8")
    except UnicodeDecodeError:
        errors.append("File is not valid UTF-8")

    try:
        root = ET.fromstring(raw)
    except ET.ParseError as e:
        return [f"XML does not parse: {e}"], warnings

    if root.tag == NS + "sitemapindex":
        child, kind = "sitemap", "index"
    elif root.tag == NS + "urlset":
        child, kind = "url", "urlset"
    else:
        return [f"Root element is {root.tag}; expected urlset or sitemapindex in the sitemaps.org namespace"], warnings

    entries = root.findall(NS + child)
    if len(entries) > MAX_URLS:
        errors.append(f"{len(entries):,} entries; the limit is {MAX_URLS:,} per file")

    seen, hosts = set(), set()
    for i, entry in enumerate(entries, 1):
        loc_el = entry.find(NS + "loc")
        if loc_el is None or not (loc_el.text or "").strip():
            errors.append(f"Entry {i}: missing <loc>")
            continue
        loc = loc_el.text.strip()
        parsed = urlparse(loc)
        if parsed.scheme not in ("http", "https") or not parsed.netloc:
            errors.append(f"Entry {i}: <loc> is not an absolute URL: {loc}")
        if len(loc) >= 2048:
            errors.append(f"Entry {i}: <loc> is 2,048 characters or longer")
        if loc in seen:
            warnings.append(f"Entry {i}: duplicate URL {loc}")
        seen.add(loc)
        if parsed.netloc:
            hosts.add(parsed.netloc)

        lastmod = entry.find(NS + "lastmod")
        if lastmod is not None and not valid_w3c_date((lastmod.text or "").strip()):
            errors.append(f"Entry {i}: <lastmod> is not a W3C Datetime: {lastmod.text}")

        if kind == "urlset":
            cf = entry.find(NS + "changefreq")
            if cf is not None and (cf.text or "").strip() not in {
                "always", "hourly", "daily", "weekly", "monthly", "yearly", "never"
            }:
                warnings.append(f"Entry {i}: unexpected <changefreq> {cf.text}")
            pr = entry.find(NS + "priority")
            if pr is not None:
                try:
                    if not 0.0 <= float(pr.text) <= 1.0:
                        raise ValueError
                except (TypeError, ValueError):
                    warnings.append(f"Entry {i}: <priority> must be 0.0 to 1.0, got {pr.text}")

    if len(hosts) > 1:
        warnings.append(f"URLs span several hosts: {', '.join(sorted(hosts))}")

    print(f"{kind}: {len(entries):,} entries")
    return errors, warnings


if __name__ == "__main__":
    errs, warns = check(sys.argv[1])
    for e in errs:
        print("ERROR  ", e)
    for w in warns:
        print("WARNING", w)
    sys.exit(1 if errs else 0)

Run it against a file or a live URL:

python3 check_sitemap.py public/sitemap.xml
python3 check_sitemap.py https://www.example.com/sitemap.xml

Against a deliberately broken test file, the output looks like this:

urlset: 5 entries
ERROR   Entry 2: <loc> is not an absolute URL: /pricing
ERROR   Entry 4: <lastmod> is not a W3C Datetime: 20/10/2026
WARNING Entry 3: duplicate URL https://example.com/
WARNING Entry 3: <priority> must be 0.0 to 1.0, got 2
WARNING Entry 4: unexpected <changefreq> often
WARNING URLs span several hosts: example.com, www.example.com

And a file with an unescaped & fails at the parse step, before any entry checks:

ERROR   XML does not parse: not well-formed (invalid token): line 1, column 117

A few notes on the choices:

Errors are things that break the protocol or the parse. Warnings are things that are valid XML but probably wrong.
The host check is a warning, not an error, because cross-host sitemaps are allowed if you've proven ownership of the hosts (sitemaps.org describes how).
It doesn't handle gzipped sitemaps. If you serve .xml.gz, wrap load() with gzip.decompress().
For a sitemap index, it checks the index itself. To validate the child sitemaps, loop over the <loc> values and call check() on each.

Optional: check that listed URLs actually resolve

Protocol-valid isn't the same as useful. Here's a quick status-code pass that flags anything other than a 200:

import urllib.request
import xml.etree.ElementTree as ET

NS = "{http://www.sitemaps.org/schemas/sitemap/0.9}"

def status_report(sitemap_path, limit=200):
    root = ET.parse(sitemap_path).getroot()
    locs = [el.text.strip() for el in root.iter(NS + "loc")][:limit]
    for url in locs:
        req = urllib.request.Request(url, method="HEAD",
                                     headers={"User-Agent": "sitemap-check/1.0"})
        try:
            with urllib.request.urlopen(req, timeout=15) as resp:
                final = resp.geturl()
                if final != url:
                    print("REDIRECT", url, "->", final)
        except urllib.error.HTTPError as e:
            print(e.code, url)
        except Exception as e:
            print("FAIL", url, e)

urlopen follows redirects, so the script compares the final URL with the listed one to catch them. Some servers reject HEAD requests; switch to GET if you see a lot of 405s. Keep the limit low and be polite to your own server.

Wiring it into CI

Generate the sitemap during the build, then validate it before deploying. A GitHub Actions step is enough:

- name: Validate sitemap
  run: python3 scripts/check_sitemap.py dist/sitemap.xml

Because the script exits with 1 on errors, a broken sitemap fails the build. Warnings print but don't block.

Two more habits that pay off:

Diff the URL list on each release. A release that drops 3,000 URLs from the sitemap is worth a look before it ships.
Reference the sitemap from robots.txt. Google says it will find a Sitemap: line in robots.txt the next time it crawls that file:

Sitemap: https://www.example.com/sitemap.xml

If you'd rather not run code

Appie.run has a set of free sitemap tools at appie.run/tools that cover the same ground in a browser. Each asks you to complete a Cloudflare Turnstile check before it runs:

XML Sitemap Validator: paste XML or a sitemap URL. It checks the root element, absolute URLs, lastmod, changefreq, priority, duplicates and the 50,000 URL limit, and gives a score that starts at 100 and drops for errors and warnings.
Sitemap Finder and Checker: enter a site URL. It reads Sitemap: lines in robots.txt, then tries /sitemap.xml, common sitemap index paths and the WordPress sitemap path, and reports which files load and how many URLs each lists.
Sitemap URLs Comparison: compare a "before" and "after" sitemap and get the added and removed URLs, which is the release diff above without writing code.
Sitemap Split and Merger: splits sets over 50,000 URLs into parts plus a sitemap index (you then replace the index locations with your real URLs).

They're handy for a one-off audit or for a client site where you can't add a CI step.

FAQ

How do I check if my XML sitemap is valid?

Parse it as XML, confirm the root is urlset or sitemapindex in the sitemaps.org namespace, and check each <loc> is an absolute, escaped URL under 2,048 characters, with at most 50,000 URLs and 50MB uncompressed per file. The script above does this, or use a browser-based validator.

Does Google use priority and changefreq?

No. Google's documentation says it ignores both. It uses lastmod when it's consistently and verifiably accurate.

What is the maximum size of a sitemap?

50,000 URLs or 50MB uncompressed per file. For more, split into several sitemaps and list them in a sitemap index.

Why does my sitemap say "XML parse error"?

The most common cause is an unescaped & in a URL. Replace it with &. Other causes include stray characters before the XML declaration and invalid UTF-8.

RG, Founder, Appie.run

How to Convert PDFs to Markdown for RAG and Chatbots (and When Not To)

appierun — Sat, 24 Oct 2026 15:48:28 +0000

Markdown keeps a document's headings, lists and tables in plain text that chunkers and LLMs handle well, so it's a sensible format to put between a PDF and your vector store. PDFs with a real text layer convert cleanly. Scanned PDFs need OCR first. Tables, multi-column layouts and repeated headers are where conversions usually go wrong, so check the output before you embed it.

Disclosure: this post is published by Appie.run. One of the conversion routes below is Appie's free converter and one section mentions Appie's chatbot product. The open-source routes work just as well, and for batch jobs they're the better choice.

Why Markdown before embedding

Three practical reasons:

Headings give you chunk boundaries. A ## Refunds heading is a natural place to split. Plain text extracted from a PDF loses that signal, and you end up splitting every N characters, often mid-sentence or mid-table.
Cleaner, smaller context. Markdown carries structure with very little markup. You avoid sending the model layout noise such as page furniture, odd line breaks and font artefacts.
Citations. If you keep the heading and page number with each chunk, your bot or RAG app can say where an answer came from. That matters for policies, contracts and manuals, where people will want to check the source.

Markdown isn't magic, though. If the PDF has no text layer or the converter scrambles the reading order, the Markdown will be just as wrong as the plain text would have been.

Step 1: check what kind of PDF you have

Before choosing a tool, find out whether the PDF has a text layer.

The manual check: open it in any PDF viewer and try to select a sentence. If the text highlights word by word, there's a text layer. If you can only draw a box around the whole page, it's an image, which usually means a scan or a photo.

The scripted check (for a folder of files) uses PyMuPDF. Since PyMuPDF 2.x the Markdown helpers that used to live in the separate pymupdf4llm package ship inside pymupdf itself (per the pymupdf4llm repo, which is now an empty compatibility package).

# pip install --upgrade pymupdf
import pymupdf

doc = pymupdf.open("policy.pdf")
for number, page in enumerate(doc, start=1):
    chars = len(page.get_text().strip())
    flag = "OK" if chars > 50 else "NO TEXT LAYER? needs OCR"
    print(f"page {number}: {chars} characters  {flag}")

The 50-character threshold is arbitrary. A page that is mostly a diagram will also come back low, so treat the result as a prompt to look, not a verdict. We ran this against a small test PDF with PyMuPDF 2.0; adapt it for your setup.

Step 2: convert

Pick the route that matches the job.

Route A: a free web converter for one-off files

If you have one policy document or one manual and want Markdown in a minute, a web converter is the fastest path. Appie's free Convert PDF to Markdown tool (ours) extracts each page to Markdown, and you copy or download the result. Its limits, as stated on the tool page on 22 Oct 2026:

PDFs with real text only. A photo scan needs OCR first.
The first 30 pages are included.
You complete a Cloudflare Turnstile captcha before it runs.

For anything longer than 30 pages or for a recurring job, use a library.

Route B: a Python library for batches

Four open-source options are worth a look. Descriptions below are taken from each project's own README, read on 22 Oct 2026; test them on your own documents, because results vary by layout.

PyMuPDF: its README lists "native Markdown output for RAG and AI pipelines" via doc.to_markdown(). Lightweight and quick to install.
Marker: converts PDF, images, PPTX, DOCX, XLSX, HTML and EPUB to Markdown, JSON and chunks. The README says it formats tables, equations and code blocks, removes headers and footers, and can optionally call an LLM to improve accuracy. Runs on GPU, CPU or MPS.
Docling: parses many formats with "advanced PDF understanding" including page layout, reading order and table structure, and exports Markdown, HTML and lossless JSON.
MarkItDown (Microsoft): a lightweight utility for converting PDF, Office files, HTML and more to Markdown for LLM pipelines. Its README is candid that output is meant for text analysis tools, not high-fidelity human-readable conversion. It also warns that it performs I/O with the privileges of the current process, so sanitise inputs in untrusted environments.

A minimal batch script with PyMuPDF:

import pathlib
import pymupdf

src = pathlib.Path("pdfs")
out = pathlib.Path("markdown")
out.mkdir(exist_ok=True)

for pdf in src.glob("*.pdf"):
    md = pymupdf.open(pdf).to_markdown()
    (out / f"{pdf.stem}.md").write_text(md, encoding="utf-8")
    print("converted", pdf.name)

Tested with PyMuPDF 2.0 on a two-page sample; adapt for your setup.

Route C: OCR first for scans

If Step 1 flagged pages without a text layer, you need OCR before (or as part of) conversion. Marker and Docling both list scanned-document handling in their READMEs, and MarkItDown lists OCR for images. Another approach is to run an OCR tool that adds a text layer to the PDF, then use Route A or B. Whatever you pick, OCR output needs a closer review than a born-digital PDF: check numbers, names and anything in a table.

Step 3: clean up

Run through this checklist on a sample of the output before converting hundreds of files:

Headers and footers. Company name, document title and "Page 4 of 37" repeated on every page will pollute every chunk. Strip them with a regex or your converter's option.
Tables. Open a few tables in a Markdown preview. Merged cells and tables that span two pages are common failure points. If a table is critical (a price list, a spec sheet), consider fixing it by hand or storing it as CSV alongside the Markdown.
Reading order in multi-column layouts. Read a two-column page top to bottom. If paragraphs from the left and right columns interleave, try a layout-aware converter.
Hyphenation. Words split across lines ("con-\nversion") hurt search. Rejoin them.
Page markers. Keep a page reference somewhere (a comment such as  or chunk metadata) so you can cite it later.
Images and charts. Most converters drop them or emit a placeholder. If a chart holds the answer to likely questions, describe it in text.

Step 4: chunk by heading and keep page numbers

Chunk on headings first, then split long sections by size. Keep the heading and page number as metadata on every chunk. Here's a small example using PyMuPDF's per-page output:

import re
import pymupdf

pages = pymupdf.open("policy.pdf").to_markdown(page_chunks=True)  # one dict per page

chunks = []
for page in pages:
    page_no = page["metadata"]["page_number"]
    # split before each H1 to H3 heading, keeping the heading with its text
    for section in re.split(r"\n(?=#{1,3} )", page["text"]):
        section = section.strip()
        if section:
            heading = section.splitlines()[0].lstrip("# ").strip()
            chunks.append({"text": section, "heading": heading, "page": page_no})

This splits per page, so a section that runs across a page break becomes two chunks. That's usually fine for retrieval, and the page numbers stay accurate. If you'd rather keep sections whole, convert the full document, split on headings, and record page numbers from the page markers you added in Step 3. Tested on a two-page sample with PyMuPDF 2.0; adapt for your setup.

A few rules of thumb (general guidance, not benchmarks):

Prepend the heading path to each chunk's text ("Refund policy > EU orders") so the embedding knows the context.
Keep tables whole inside one chunk where you can.
Store the source file name with the page number, so answers can link back.

Skip the pipeline: upload the PDF straight to a hosted chatbot

If your goal is a support bot or an internal Q&A assistant, rather than a custom RAG system, you may not need any of the above. Many hosted chatbot builders accept PDFs directly and handle extraction and chunking for you; check whether the one you use does.

Appie AI Chatbots (ours) accepts PDFs, DOCX, CSV and text, plus URLs, sitemaps and product feeds, as knowledge sources (appie.run/ai-chatbots). Creating a bot is free, and each conversation with the bot costs 1 credit (pricing, as of 22 Oct 2026). The Free plan includes 500 credits and needs no credit card. It's a hosted bot, so you don't control the chunking; if you need that control, build the pipeline above.

To test whether a PDF answers questions well before building anything, try Appie's free AI Chat With Your PDF tool. You upload a text-based PDF and ask for a summary or a specific fact; per the tool page, answers must come from the PDF, and if the fact isn't there it says so. If it can't find answers you know are in the document, the PDF probably has a text-layer or layout problem to fix first.

For hosted options, see best AI chatbots trained on your own website data.

Before you choose a hosted option, compare what an AI support chatbot really costs in 2026, since per-conversation, per-credit and per-resolution pricing add up very differently.

FAQ

How do I convert a PDF to Markdown for free?

For a single text-based PDF, use a free web converter such as Appie's Convert PDF to Markdown (first 30 pages, text PDFs only). For batches, use an open-source library such as PyMuPDF (doc.to_markdown()), Marker, Docling or MarkItDown.

Can I convert a scanned PDF to Markdown?

Only after OCR. A scan is an image of text, so a converter has nothing to extract until OCR adds a text layer. Some libraries, such as Marker and Docling, include OCR; review OCR output carefully.

Is Markdown better than plain text for RAG?

Usually, because headings, lists and tables survive, which gives you better chunk boundaries and lets you keep section context for citations. It won't fix a bad extraction, so check the output either way.

How should I chunk Markdown from a PDF?

Split on headings first, then split long sections by size. Keep the heading path, source file and page number as metadata on each chunk, and keep tables whole where you can.

Convert a text PDF to Markdown free (first 30 pages): appie.run/tools/convert-pdf-to-markdown. Or upload the PDF straight into an Appie chatbot; the Free plan has 500 credits and needs no credit card. More free tools: appie.run/tools.

Track LinkedIn Profiles and Pull Leads Into Claude or Cursor

appierun — Fri, 23 Oct 2026 15:53:52 +0000

You can keep a LinkedIn watch list and work its leads from your AI client with three MCP tool calls: set_linkedin_profile to add a profile, get_linkedin_profiles to check the list, and list_linkedin_leads to see the people who engaged, with email and phone when a lookup has found them.

Disclosure: Appie.run publishes this post, and the MCP server below is ours. Other LinkedIn MCP servers exist, and our LinkedIn MCP servers explainer compares the kinds you'll find. This walkthrough covers Appie's only.

Who this is for

GTM engineers and RevOps people who already live in Claude Code, Cursor or Codex.
Outbound agencies watching customers, partners, competitors' founders or industry voices.
Teams moving off Trigify, whose access ended on 22 October 2026 for most customers. We have a separate Trigify alternatives piece.

Step 1: Key and server

In Appie, open your project and choose API in the sidebar. A project admin generates the esk_ key. Set it once in your shell:

export APPIE_API_KEY=esk_your_key_here

The server is https://appie.run/mcp, and it accepts Authorization: Bearer esk_â€¦ or X-Api-Key: esk_â€¦.

Claude Code:

claude mcp add --transport http appie https://appie.run/mcp \
  --header "Authorization: Bearer $APPIE_API_KEY"

Codex CLI:

codex mcp add appie --url https://appie.run/mcp --bearer-token-env-var APPIE_API_KEY

Cursor and other clients (config from the Appie docs):

{
  "mcpServers": {
    "appie": {
      "url": "https://appie.run/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

With a valid key, claude mcp list should show the server as connected. A 401 means the key is wrong or revoked. The Reddit MCP walkthrough covers scopes, .mcp.json and troubleshooting in more detail.

Step 2: Add the profiles you want to watch

set_linkedin_profile adds or updates one profile. profile_url is required, and tracking_enabled defaults to true.

{
  "profile_url": "https://www.linkedin.com/in/example"
}

To pause a profile without removing it:

{
  "profile_url": "https://www.linkedin.com/in/example",
  "tracking_enabled": false
}

Saving a profile doesn't spend credits. In the docs' words, "the existing schedule runs the scan, which costs 30 credits." The docs don't say how often that schedule runs, so check the project settings in the app before you add a long list.

Step 3: Check your watch list

get_linkedin_profiles lists the profiles the project tracks. It takes no required arguments and doesn't spend credits. Ask your agent to show it as a table with tracking status, so you can spot anything you paused by mistake.

Step 4: List leads by profile

Leads are the people who engage with the profiles you track. list_linkedin_leads takes an optional limit (default 20, maximum 50) and an optional tracked_profile_id, which you get from Step 3.

{
  "tracked_profile_id": "PROFILE_ID_FROM_STEP_3",
  "limit": 50
}

Each lead includes email and phone when a lookup has found them. Listing is free. The lookup that fills email and phone costs 5 credits per lead.

Illustrative shape of one lead (not real output; only email and phone are field names the docs confirm):

lead: Example Person, engaged with https://www.linkedin.com/in/example
email: person@example.com
phone: (empty, no lookup result)

What the docs don't cover: whether the email lookup runs automatically or has to be triggered (no lookup tool is listed in the MCP), whether ICP scores come back over MCP, and which other fields are returned. Run the tool once and read the response before you build on it.

Step 5: Do something useful with them

Two common routes:

Keep it in your own stack. Ask your agent to turn the leads with an email into a CSV or rows for your sheet or CRM.
Stay inside Appie. The app groups leads by source profile with new, emailed and contacted counts, scores them against project-level ICP weights, shows posts from tracked profiles next to the people, and can hand a lead into a Journeys sequence once an email is found. Appie's page puts it as "no surprise sends from a profile sync": you choose who gets contacted.

The MCP has no messaging, connection-request or posting tools. Your agent can read and list; a person decides who to contact and what to say. For the outreach side, see From Likes to Replies: How to Turn LinkedIn Engagement Into Leads With Warm Outreach.

If you're writing first emails by hand, two free Appie tools help:

AI Email Response Generator: paste an email, choose a language and tone, and get a draft with subject, greeting, body and sign-off. Review it before you send.
Email Signature Generator: builds an HTML signature in your browser for Gmail, Outlook or Apple Mail.

If you used Outfunnel to sync LinkedIn engagement into your CRM, here are Outfunnel alternatives to switch to before its shutdown dates.

Prompts to paste

"Add these five LinkedIn profile URLs to Appie and confirm tracking is on for each: â€¦"
"List my tracked LinkedIn profiles as a table with their IDs and tracking status."
"Show leads from tracked profile PROFILE_ID that have an email, as a table. Leave out anyone without one."
"Turn those leads into CSV rows with name, email and source profile so I can import them."

What it costs

Save or update a profile (set_linkedin_profile): Credits: 0
List profiles (get_linkedin_profiles): Credits: 0
List leads (list_linkedin_leads): Credits: 0
Scheduled profile scan: Credits: 30 per profile
Lead email lookup: Credits: 5 per lead

Illustrative example: 5 tracked profiles cost 150 credits per scheduled scan, and 40 email lookups cost 200 credits. That's 350 credits, inside the Free plan's 500 for a single run. How many scans happen in a month depends on the schedule, so work out your monthly number from that.

Plans (appie.run/pricing, as of 20 Oct 2026): Free is $0 with 500 credits and no credit card needed. Starter is $19/month for 2,000 credits. Standard is $49/month for 5,000 credits.

Appie gets LinkedIn data through third-party vendor APIs.

Responsible use

You're collecting data about real people. Read LinkedIn's terms yourself. For leads in the EU or UK, GDPR applies: have a lawful basis, keep only the data you need, and honour opt-outs. Check with your own advisers. Appie doesn't make that decision for you, and this post isn't legal advice.

FAQ

How do I track LinkedIn profile engagers from Claude?
Connect the Appie MCP server, add profiles with set_linkedin_profile, then call list_linkedin_leads to see the people who engaged with them.

Can an MCP server find emails for LinkedIn leads?
Appie's list_linkedin_leads returns email and phone when a lookup has found them. Each lookup costs 5 credits per lead. The MCP doesn't list a separate lookup tool, so check the docs for how lookups run.

How much does a LinkedIn profile scan cost in Appie?
30 credits per profile scan. Saving and listing profiles is free.

Can Claude send LinkedIn messages through Appie?
No. The MCP has no messaging, connection or posting tools.

Add your watch list with set_linkedin_profile and list your first leads from Cursor or Claude: appie.run/docs/mcp

Find Reddit Threads and Draft Replies From Claude Code or Cursor

appierun — Thu, 22 Oct 2026 15:47:56 +0000

The whole loop takes five steps: connect one MCP server, save your keywords and competitors, list today's threads, draft a reply, and paste it on Reddit yourself. This walkthrough uses Appie.run's MCP server, with every tool name and credit cost taken from appie.run/docs/mcp on 22 Oct 2026.

Disclosure: this post is published by Appie.run, and the server used here is ours. Other Reddit MCP servers exist; see our roundup of Reddit MCP servers for marketing. Appie drafts replies but never posts them.

What you need

An Appie project (the Free plan has 500 credits, no credit card needed).
A project API key that starts with esk_.
Cursor, Claude Code or Codex CLI.

Step 1: Create the key

In Appie, open the project and go to API in the sidebar. A project admin generates one esk_ key.

Two things to know before you use it:

The same key is used by Event Store. Regenerating it stops both immediately, so update every client at once.
The key has no balance of its own. A paid tool runs on the project's credits first, then the project owner's. Every tool result includes credits_remaining.

Set it once in your shell:

export APPIE_API_KEY=esk_YOUR_KEY

Never commit the key or paste it in public.

Step 2: Add the server

The server is https://appie.run/mcp (streamable HTTP). It accepts Authorization: Bearer esk_... or X-Api-Key: esk_....

Cursor. Add this to your MCP config (from Appie's docs):

{
  "mcpServers": {
    "appie": {
      "url": "https://appie.run/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Code. One command:

claude mcp add --transport http appie https://appie.run/mcp \
  --header "Authorization: Bearer $APPIE_API_KEY"

--transport http is required; without it, Claude Code treats the URL as a local command. The default scope is local (you, this project). Add --scope user to use it everywhere. Your shell expands $APPIE_API_KEY, so the key itself is saved in ~/.claude.json.

To share the server with a repo without committing the key, use a project .mcp.json:

{
  "mcpServers": {
    "appie": {
      "type": "http",
      "url": "https://appie.run/mcp",
      "headers": { "Authorization": "Bearer ${APPIE_API_KEY}" }
    }
  }
}

Check it with claude mcp list. With a valid key, the status should read Connected. Note that claude mcp get appie prints the header value in plain text, so don't share that output.

Codex CLI.

codex mcp add appie --url https://appie.run/mcp --bearer-token-env-var APPIE_API_KEY

This writes the following to ~/.codex/config.toml:

[mcp_servers.appie]
url = "https://appie.run/mcp"
bearer_token_env_var = "APPIE_API_KEY"

Codex stores only the variable name and reads the key each time it starts. codex mcp list reads the config but doesn't connect. Start codex and run /mcp to see the tools.

Smithery. Paste the key into the apiKey field. Smithery sends it as X-Api-Key.

The commands above were run against appie.run with a placeholder key (which returned the expected 401). The success output described here is what you should expect with a real key, not something we captured.

Step 3: Check and set your Reddit settings

Ask your agent to call get_reddit_settings. It's free. If you haven't saved anything yet and your project Brain has a website, about text, key messages or competitors, Appie saves those as your Reddit settings and returns them. That gives you a starting point.

Then refine with update_reddit_settings (also free). Send only the fields you want to change: keywords, competitors or custom_prompt. Each list holds up to 25 items. Illustrative arguments:

{
  "keywords": ["reddit monitoring", "social listening for startups", "find leads on reddit", "brand mentions tool", "reply to reddit threads"],
  "competitors": ["CompetitorA", "CompetitorB", "CompetitorC"],
  "custom_prompt": "Help first. Disclose that I work on the product. No links unless asked."
}

The docs don't say whether a list replaces or appends to what's saved. Send the full list each time, and check the response to see what was stored.

Step 4: List today's mentions

Call list_reddit_mentions. It lists Reddit threads for your saved keywords and competitors, with the latest reply draft for each. limit defaults to 20, maximum 50.

A scan runs at most once per day and costs 10 credits. Calling it again the same day lists results without a new scan. If your balance is too low, the result has scan_skipped: true and a message saying no scan ran.

This is a monitored feed of your terms, not a search of all of Reddit, and it isn't real-time.

To decide which of those threads are worth a reply at all, see how to find buyer-intent Reddit threads without spamming anyone.

Step 5: Draft a reply and post it yourself

Pick a mention and call draft_reddit_reply with its mention_id. It costs 2 credits and returns content (the draft) and source_url (the thread). Illustrative shape:

{ "content": "...", "source_url": "https://www.reddit.com/r/...", "credits_remaining": 488 }

(The credits_remaining number is only an example.)

Then:

Open the thread and read the whole conversation.
Check the subreddit's rules on self-promotion.
Edit the draft so it answers the question first.
Disclose that you work on the product if you mention it.
Paste it from your own account.

Appie doesn't post to Reddit. If you only need a one-off draft for a thread you found yourself, Appie's free AI Reply Generator takes the message, a style and a length, and returns an editable reply without any setup.

If the thread is a complaint about your product, read how to respond to negative brand mentions before you edit the draft.

Prompts to paste

"Call get_reddit_settings and show me what's saved. Suggest five more buyer-intent keywords."
"List today's Reddit mentions and group them by buying intent: asking for a tool, comparing tools, complaining, other."
"Draft a reply to the top 'asking for a tool' mention. Answer the question first and mention us only at the end, with a disclosure."
"Show credits_remaining after each call."

What it costs

get_reddit_settings: Credits (as of 22 Oct 2026): 0
update_reddit_settings: Credits (as of 22 Oct 2026): 0
list_reddit_mentions: Credits (as of 22 Oct 2026): 10 per scan, at most one scan per day
draft_reddit_reply: Credits (as of 22 Oct 2026): 2 per draft

Worked example (illustrative arithmetic from the docs, not a promise of usage): a daily scan for 30 days is 300 credits, and 50 drafts are 100 credits. Together that's 400 of the Free plan's 500 credits. Paid plans are Starter at $19/month (2,000 credits) and Standard at $49/month (5,000 credits), per appie.run/pricing.

Troubleshooting

HTTP 401. The key is missing, wrong or was regenerated. Copy the current esk_ key from the API page. In Claude Code, a 401 with an Authorization header set means a bad key, not an OAuth prompt.
app_not_allowed. The person who generated the key can't use the Reddit app in that project. A project owner can use every app.
insufficient_credits. The response includes required and available. Top up or wait for your next cycle.
Codex shows no Appie tools. Check echo $APPIE_API_KEY in the same shell that starts Codex.
Empty results. Widen your keywords: add problem phrases your buyers type, not only your brand name.

FAQ

How do I connect a Reddit MCP server to Cursor?

Add the server URL and an Authorization header to your Cursor MCP config, as in Step 2.

How do I add an MCP server with an API key in Claude Code?

claude mcp add --transport http <name> <url> --header "Authorization: Bearer <key>".

Can Claude post to Reddit for me?

Not with Appie. It drafts the reply, and you paste it yourself.

How often does the Reddit scan run?

At most once per day, at 10 credits per scan.

Grab an API key, add https://appie.run/mcp to Cursor, and run your first Reddit scan on the Free plan's 500 credits: appie.run/docs/mcp. Skills and examples are also on GitHub.

Reddit MCP Servers for Marketing (2026): Find Threads and Draft Replies From Claude, Cursor or Codex

appierun — Wed, 21 Oct 2026 16:00:38 +0000

Reddit doesn't publish an official MCP server, so every option below comes from a third party. The right one depends on the job: researching all of Reddit, working a monitored feed with reply drafts, or posting (which we suggest you keep doing by hand). Prices and features below were checked on each vendor's own site on 21 Oct 2026.

Disclosure: this article is published by Appie.run, and Appie is one of the servers compared here. We've placed it by job, not at the top.

What a Reddit MCP server does

MCP (Model Context Protocol) is an open standard that lets an AI client such as Claude, Claude Code, Cursor or Codex call outside tools. A Reddit MCP server exposes tools like "search posts", "list my mentions" or "draft a reply", and your agent calls them in the middle of a conversation. Most hosted servers need only a URL and a key or sign-in. A typical client config looks like this:

{
  "mcpServers": {
    "reddit-tool": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

If you rely on Reddit RSS feeds for keyword alerts today, check whether your Reddit keyword alerts will keep working after Reddit ends RSS and its public API.

Is there an official Reddit MCP server?

No. Redreach's MCP page states that "Reddit does not publish an official MCP server," and Manifold's server page says Reddit "has no MCP server of its own" and that new API apps need Reddit's approval. Both are vendor pages, so treat them as vendor statements.

One thing to watch: Reddit is closing its public Data API in stages. New public API requests stop on 31 October 2026, and remaining access ends in March 2027, per Reddit's 8 October changelog. Every server here gets Reddit data in its own way, so ask each vendor how.

Comparison table

Manifold: Hosted or local: Hosted; Your own Reddit credentials?: No (reads "through a data provider"); All of Reddit or your monitored feed: Search all of Reddit, plus new posts in named subreddits; Drafts replies: Your agent drafts; Posts to Reddit: No; Price (as of 21 Oct 2026): Credits per call, "from 1 credit"; 250 free credits a month
Redreach: Hosted or local: Hosted; Your own Reddit credentials?: No; All of Reddit or your monitored feed: Your scored feed: tracked keywords, Google-ranking threads, mentions; Drafts replies: Yes; Posts to Reddit: No; Price (as of 21 Oct 2026): Included on Growth, Professional and Agency plans (price not shown in what we could read)
RedShip: Hosted or local: Hosted; Your own Reddit credentials?: No; All of Reddit or your monitored feed: Your ranked inbox; Drafts replies: Your agent drafts from the thread; Posts to Reddit: No; Price (as of 21 Oct 2026): Founder $29/month, Company $49/month, 7-day pass $12
Mentio: Hosted or local: Hosted; Your own Reddit credentials?: No; All of Reddit or your monitored feed: Your keywords across Reddit and many other platforms; Drafts replies: Your agent drafts; Posts to Reddit: No; Price (as of 21 Oct 2026): $5 per keyword/month + $0.008 per mention
Appie.run (ours): Hosted or local: Hosted; Your own Reddit credentials?: No; All of Reddit or your monitored feed: Your saved keywords and competitors; Drafts replies: Yes, 2 credits; Posts to Reddit: No; Price (as of 21 Oct 2026): Free plan (500 credits), Starter $19/mo, Standard $49/mo
Syften PRO: Hosted or local: Hosted; Your own Reddit credentials?: No; All of Reddit or your monitored feed: Your filters across communities; Drafts replies: No; Posts to Reddit: No; Price (as of 21 Oct 2026): MCP on PRO only, $119.95/month
Octolens: Hosted or local: Hosted; Your own Reddit credentials?: No; All of Reddit or your monitored feed: Your keywords across platforms; Drafts replies: No; Posts to Reddit: No; Price (as of 21 Oct 2026): Pro $159/mo billed annually

The servers

Manifold: hosted Reddit research

Manifold's Reddit server lives at https://mcp.manifoldmcp.com/mcp and connects with OAuth or an API key. Its tools search posts and comments across Reddit or one community, find subreddits for a topic, read a subreddit's rules, list every new post in named subreddits within a time window, and read a full thread with comments. It says it reads Reddit "through a data provider". Calls cost "from 1 credit", and every workspace gets 250 free credits a month. Manifold also says search is ranked and "never returns everything." Good for: research and one-off questions about all of Reddit.

Redreach: scored marketing feed with reply drafts

Redreach (https://connect.redreach.ai/mcp, browser OAuth or an rr_ token) gives your agent a filtered slice rather than raw Reddit: threads that rank on Google for your keywords, threads matching tracked keywords, and brand or competitor mentions with sentiment. Its get_thread tool returns the post and comment tree for threads it has indexed for your project, and it drafts replies in several tones. It says it never posts to Reddit for you. MCP is included on its Growth, Professional and Agency plans. Good for: teams that want Google-ranking threads and mention reports.

RedShip: ranked reply inbox for founders

RedShip (https://mcp.redship.io) exposes seven tools per its docs: get_project_context, get_top_opportunities, list_inbox, get_inbox_item, get_inbox_stats, update_inbox_item and log_reply. The loop it teaches is: read context, get the top opportunities, read the full post, you post the reply yourself, then mark it replied and log the text. Pricing on 21 Oct 2026: Founder $29/month, Company $49/month, and a 7-day full-access pass for $12. Good for: a solo founder who wants a daily shortlist and reply streaks.

Mentio: multi-platform monitor with pay-per-keyword pricing

Mentio (https://mcp.mentio.dev/mcp) monitors keywords on Reddit and many other platforms, including X, Hacker News, GitHub, LinkedIn and YouTube, and scores relevance, sentiment and intent. It lists Reddit as "real time." Pricing is usage-based: $5 per keyword per month, charged daily, plus $0.008 per mention found, with a one-time $5.80 welcome credit (as of 21 Oct 2026). MCP calls aren't billed. Good for: watching Reddit alongside several other sources on a small, variable budget.

Appie.run: Reddit settings, a daily scan and reply drafts on one key (ours)

Appie's server is https://appie.run/mcp, authenticated with a project API key (Authorization: Bearer esk_...) that a project admin generates under API in the app. It has four Reddit tools, per appie.run/docs/mcp:

get_reddit_settings: reads your keywords, competitors and reply guidance. If none are saved, it seeds them from the project Brain. Free.
update_reddit_settings: sets keywords, competitors or a custom prompt, up to 25 items per list. Free.
list_reddit_mentions: lists threads for your saved terms with the latest draft (default 20, max 50). A scan runs at most once per day and costs 10 credits. If your balance is too low, it returns scan_skipped.
draft_reddit_reply: writes a reply for one mention and returns the text plus the thread URL. 2 credits. Appie doesn't post to Reddit; you paste the reply.

The same key reaches Appie's LinkedIn, articles, chatbot, short-link and Brain tools (21 tools in total). Honest limits: it's a monitored feed of your keywords and competitors, not a search of all of Reddit; it scans once a day, not in real time; and there's no documented tool for reading a full comment tree. Pricing on 21 Oct 2026: Free plan with 500 credits and no credit card needed, Starter $19/month (2,000 credits), Standard $49/month (5,000 credits). Good for: a once-a-day reply routine on the same server you use for other marketing jobs.

Syften PRO and Octolens: listening tools that added MCP

Syften lists MCP on its PRO plan only. Its Entry ($29.95/month) and Standard ($49.95/month) plans don't include it, and PRO is $119.95/month as of 21 Oct 2026. Syften says it aims for at most a one-minute delay on Reddit.

Octolens includes "API, webhooks and MCP on every plan." Pro is $159/month billed annually (10 keywords, 15,000 mentions, hourly search) as of 21 Oct 2026. Good for: broader listening where Reddit is one source among many.

Open-source servers

Several open-source Reddit MCP servers run locally. Some browse without keys, others need your own Reddit API credentials, and at least one can post with them, according to vendor roundups. Check each README before installing, and remember that new public API access closes on 31 October 2026.

Pick by job

Research all of Reddit: Manifold, or an open-source server if you already have API access.
A reply workflow: Redreach, RedShip or Appie. All three draft or help draft, and none posts.
Cross-platform listening with Reddit as one source: Mentio, Octolens or Syften PRO.

Want to try reply drafting before wiring up a server? Appie's free AI Reply Generator drafts a reply to a message you paste in, with a choice of style and length.

Posting from an agent

Most marketing-focused servers deliberately don't post. Reddit communities set their own rules, and many remove promotional replies. A few habits help whichever server you use:

Read each subreddit's rules before replying.
Disclose your affiliation when you mention your product.
Edit every draft and post it by hand from your own account.
Reply only where you can actually help.

FAQ

Is there an official Reddit MCP server?

No. Vendors including Redreach and Manifold say Reddit doesn't publish one.

What is the best Reddit MCP server for marketing?

It depends on the job. Research-first: Manifold. Reply workflow: Redreach, RedShip or Appie. Multi-platform listening: Mentio, Octolens or Syften PRO.

Can a Reddit MCP server post replies for me?

Some open-source servers can, using your own credentials. The marketing servers in this list don't; you post yourself.

Do I need Reddit API keys?

Not for the hosted servers above. Local open-source servers often need them.

How do I connect Reddit to Claude Code or Cursor?

Add the server URL and your key to the client's MCP config. For Appie in Claude Code: claude mcp add --transport http appie https://appie.run/mcp --header "Authorization: Bearer $APPIE_API_KEY".

How much does a Reddit MCP server cost?

From pay-per-use (Manifold credits, Mentio at $5 per keyword) to flat plans (RedShip $29/month, Syften PRO $119.95/month, Octolens $159/month billed annually), as of 21 Oct 2026. Appie starts with a Free plan of 500 credits.

To connect Appie's MCP server, save your keywords and competitors, and get reply drafts you post yourself, start with the Free plan's 500 credits: appie.run/docs/mcp.