markstream-mcp

MCP server for Markstream — convert any URL or local file into clean, agent-ready markdown, directly from your MCP client (Claude Desktop, Claude Code, Cursor, …).

It wraps the Markstream HTTP API, so your agent can read web pages (including login-walled marketing sources like Facebook & SimilarWeb) and documents (PDF, Word, Excel, CSV, images) as markdown — 1 credit per conversion, failed conversions auto-refunded.

Tools

| Tool | What it does | |---|---| | markstream_convert_url | Convert any http(s) URL to markdown. Facebook/SimilarWeb auto-route to dedicated scrapers. | | markstream_convert_file | Convert a local file (PDF, Word, Excel, CSV, image; ≤ 10 MB) to markdown. | | markstream_get_conversion | Re-fetch a past conversion's markdown by id (no extra credit). |

Each tool accepts response_format: markdown (default, returns the content) or json (returns id, title, provider, credits, char count, and the markdown).

Setup

1. Get an API key

Create one at https://markstream.dev/settings/apikeys. New accounts get free credits.

2. Add the server to your MCP client

Requires Node.js ≥ 18.

Claude Code

claude mcp add markstream \
  -e MARKSTREAM_API_KEY=msk_your_key_here \
  -- npx -y markstream-mcp

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "markstream": {
      "command": "npx",
      "args": ["-y", "markstream-mcp"],
      "env": { "MARKSTREAM_API_KEY": "msk_your_key_here" }
    }
  }
}

Cursor — add to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "markstream": {
      "command": "npx",
      "args": ["-y", "markstream-mcp"],
      "env": { "MARKSTREAM_API_KEY": "msk_your_key_here" }
    }
  }
}

Restart the client, then ask it to "convert https://example.com to markdown" or "convert ./report.pdf to markdown".

Environment variables

| Variable | Required | Default | Notes | |---|---|---|---| | MARKSTREAM_API_KEY | ✅ | — | Your Markstream API key. | | MARKSTREAM_BASE_URL | — | https://markstream.dev | Override for self-hosted/dev instances. |

Usage examples

• "Convert https://blog.example.com/post to markdown and summarize it."
• "Pull this competitor's SimilarWeb traffic: https://www.similarweb.com/website/competitor.com/"
• "Convert ./contracts/agreement.pdf to markdown so we can extract the key terms."
• "Re-fetch the full markdown for conversion V1StGXR8_Z5jdHi6B-myT."

Notes & limits

• Credits: 1 per conversion. Failed conversions are automatically refunded.
• Rate limit: 60 requests/minute per key.
• Files: max 10 MB. HTML uploads are rejected — convert web pages with markstream_convert_url instead.
• Large outputs are truncated at ~25,000 characters; fetch the full markdown via markstream_get_conversion (json) or the API.

Local development

pnpm install
pnpm build            # tsc → dist/
MARKSTREAM_API_KEY=… node dist/index.js   # runs over stdio

To point a client at a local build, use node /absolute/path/to/mcp/dist/index.js as the command (no args) instead of npx.

License

MIT