@aporialab/telegraph-mcp

MCP server connecting Claude Desktop to the Telegraph AI publishing pipeline.

Overview · Installation · Configuration · Tools · Examples · Contributing

Overview

@aporialab/telegraph-mcp is a Model Context Protocol (MCP) server that connects Claude Desktop directly to your Telegraph AI publishing workflow.

Instead of copy-pasting content between Claude and your publishing pipeline, this server exposes your Telegraph pipeline as native tools within Claude's context. You describe what you want to publish, Claude calls the appropriate tool, and the content moves through formatting, enrichment, and publishing automatically.

What Telegraph AI does:

• Compiles long-form content from multiple context sources (chat history, notes, documents)
• Auto-formats for Telegraph's node-based article format
• Enriches with metadata, tags, and cross-links
• Publishes via Telegraph's API with your account credentials

What this MCP server adds:

• Exposes the entire pipeline as Claude-native tools
• Lets Claude read your current draft context before publishing
• Enables conversational publishing: describe edits, Claude applies them, then publishes

Installation

Via Claude Desktop Configuration (Recommended)

No manual npm install needed. Add the server directly to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "telegraph-mcp": {
      "command": "npx",
      "args": ["-y", "@aporialab/telegraph-mcp"],
      "env": {
        "TELEGRAPH_ACCESS_TOKEN": "your_telegraph_access_token",
        "TELEGRAPH_AUTHOR_NAME": "Your Name",
        "TELEGRAPH_AUTHOR_URL": "https://t.me/yourchannel"
      }
    }
  }
}

Restart Claude Desktop. The Telegraph tools will appear automatically.

Manual Install

npm install -g @aporialab/telegraph-mcp

Run as a standalone MCP server:

telegraph-mcp --port 3742

Getting a Telegraph Access Token

1. Go to https://telegra.ph
2. Open browser DevTools → Network tab
3. Create any page — your access_token appears in the API call
4. Or use the Telegraph API directly:

curl https://api.telegra.ph/createAccount \
  -d "short_name=MyBot" \
  -d "author_name=My Name" \
  -d "author_url=https://t.me/mychannel"

Copy the access_token from the response.

Configuration

All configuration is passed via environment variables in the Claude Desktop config.

| Variable | Required | Description | |----------|----------|-------------| | TELEGRAPH_ACCESS_TOKEN | Yes | Your Telegraph account token | | TELEGRAPH_AUTHOR_NAME | Yes | Author name shown on published articles | | TELEGRAPH_AUTHOR_URL | No | Author URL (Telegram channel, website) | | PIPELINE_WEBHOOK | No | URL of your Telegraph AI pipeline webhook | | PIPELINE_API_KEY | No | API key for the pipeline webhook | | AUTO_FORMAT | No | true to enable auto-formatting before publish (default: true) | | CONTEXT_LIMIT | No | Max tokens to compile for context (default: 8000) |

Full Configuration Example

{
  "mcpServers": {
    "telegraph-mcp": {
      "command": "npx",
      "args": ["-y", "@aporialab/telegraph-mcp"],
      "env": {
        "TELEGRAPH_ACCESS_TOKEN": "abc123your_token_here",
        "TELEGRAPH_AUTHOR_NAME": "Aporia Labs",
        "TELEGRAPH_AUTHOR_URL": "https://t.me/aporialab",
        "PIPELINE_WEBHOOK": "https://your-n8n.example.com/webhook/telegraph-ai",
        "PIPELINE_API_KEY": "your_pipeline_key",
        "AUTO_FORMAT": "true",
        "CONTEXT_LIMIT": "12000"
      }
    }
  }
}

Available Tools

Once the server is running, Claude can call these tools:

telegraph_compile_context

Compiles the current conversation and any attached documents into a structured content brief ready for publishing.

Compile this thread into a Telegraph article draft.

Parameters:

• source — 'conversation' | 'document' | 'both'
• focus — optional focus prompt to guide compilation
• max_tokens — override context limit for this compilation

telegraph_format

Takes raw text or markdown and converts it to Telegraph's node format with proper headings, paragraphs, code blocks, and links.

Format this markdown as a Telegraph article.

Parameters:

• content — raw markdown or plain text
• title — article title
• style — 'article' | 'thread' | 'guide'

telegraph_publish

Publishes content to Telegraph and returns the live URL.

Publish the draft to Telegraph now.

Parameters:

• title — article title (required)
• content — formatted content or raw text (auto-formatted if AUTO_FORMAT=true)
• author_name — override default author name
• author_url — override default author URL

Returns:

{
  "url": "https://telegra.ph/Your-Article-Title-01-15",
  "path": "Your-Article-Title-01-15",
  "views": 0,
  "published_at": "2025-01-15T14:23:00Z"
}

telegraph_update

Updates an existing Telegraph article by path.

Update the article at telegra.ph/My-Article-01-10 with these corrections.

Parameters:

• path — Telegraph article path (e.g. My-Article-01-10)
• title — new title (optional)
• content — new content

telegraph_list

Lists recent articles from your Telegraph account.

Show my last 10 Telegraph articles.

Parameters:

• limit — number of articles to return (default: 10, max: 50)
• offset — pagination offset

telegraph_get_stats

Returns view counts and basic analytics for a published article.

How many views did my last article get?

Parameters:

• path — article path

Usage Examples

Publish a Summary of the Current Conversation

@telegraph-mcp Compile this conversation about API design patterns 
into a Telegraph article and publish it. Title: "API Design 
Patterns for 2025". Author URL: https://t.me/mydevblog

Claude will:

1. Call telegraph_compile_context to extract the key points
2. Call telegraph_format to structure the article
3. Call telegraph_publish and return the live URL

Draft First, Publish After Review

@telegraph-mcp Compile my notes into a Telegraph draft 
and show me the formatted content before publishing.

Claude shows you the formatted article. You request changes:

Rewrite the introduction to be more concise, then publish.

Claude edits and calls telegraph_publish.

Update an Existing Article

@telegraph-mcp Update telegra.ph/My-Guide-12-01 — add a 
section about rate limiting after the authentication section.

Claude fetches the article, inserts the section, and calls telegraph_update.

Batch Publish from Document

Attach a markdown document to your Claude conversation:

@telegraph-mcp This document has 5 separate articles separated 
by ---. Publish each one as a separate Telegraph article and 
give me all the URLs.

How Auto-Formatting Works

When AUTO_FORMAT=true, the server preprocesses content before publishing:

1. Heading normalisation — H1 becomes the article title; H2/H3 map to Telegraph heading nodes
2. Code block handling — triple-backtick blocks become Telegraph <code> elements with language hints
3. Link validation — external links are preserved; relative links are flagged
4. Image extraction — markdown image syntax is converted to Telegraph image nodes
5. List conversion — unordered and ordered lists map to <ul>/<ol> in Telegraph's format
6. Whitespace normalisation — double blank lines become paragraph breaks

Troubleshooting

Server not appearing in Claude Desktop

• Ensure Claude Desktop is fully restarted after editing config
• Validate your JSON config is syntactically correct
• Check Claude Desktop logs: ~/Library/Logs/Claude/ (macOS)

TELEGRAPH_ACCESS_TOKEN invalid error

• Tokens expire if unused for extended periods — generate a new one
• Ensure no extra whitespace in the token string

Content too long to publish

Telegraph articles have a ~65KB content limit. Use CONTEXT_LIMIT to reduce the compiled context size, or split into multiple articles.

Contributing

1. Fork: github.com/AporiaLab/telegraph-mcp
2. Branch: git checkout -b feat/your-feature
3. The server follows the MCP specification — new tools must implement the full tool schema
4. Add integration tests in test/ for any new tool
5. Submit a pull request

git clone https://github.com/AporiaLab/telegraph-mcp.git
cd telegraph-mcp
npm install
npm run build
npm test

For MCP development, the MCP Inspector is useful for testing tools interactively without Claude Desktop.

Support the Project

If this MCP server improved your publishing workflow, consider a Bitcoin donation:

Bitcoin:

bc1q9wpg3nrg5kywxlkkzsdd4lwkrfgd5j84jdpmjm

License

MIT License — Copyright (c) 2025 Aporia Labs

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.