Hashnode Server V2.0

A production-ready Model Context Protocol (MCP) server for Hashnode, deployable on Zeabur. Publish, update, and manage your Hashnode blog via AI assistants from anywhere!

✨ Features

Feature	Description
📝 11 Powerful Tools	Complete CRUD operations for articles
🔧 Flexible Publication ID	Use env var OR pass per-tool
🏷️ Smart Tag Handling	Auto-converts tags to Hashnode format
🖼️ Cover Images	Set cover images via URL
🔍 Search & Discovery	Search across Hashnode
📚 Publication Management	List publications, get details
🗑️ Delete Articles	Remove posts permanently
💡 Smart Errors	Clear error messages with fix hints

🛠️ Available Tools (11 Total)

Connection & Setup

Tool	Purpose
test_connection	Verify API token works
list_publications	Show your publications and IDs

Article Management

Tool	Purpose
publish_article	Publish immediately with tags, cover image
create_draft	Save as draft
update_article	Edit existing posts
delete_article	Delete permanently
get_article	Get full article details

Discovery

Tool	Purpose
list_my_articles	List your publication's articles
get_user_articles	Get articles by username
search_articles	Search across Hashnode
get_publication	Get publication info

🚀 Deploy on Zeabur

Step 1: Get Hashnode Credentials

1. Personal Access Token (PAT):

   • Go to Hashnode Developer Settings
   • Click "Generate new token"
   • Copy the token

2. Publication ID (optional - can use per-tool instead):

   • Go to your blog dashboard
   • Copy ID from URL: https://hashnode.com/{PUBLICATION_ID}/dashboard
   • Or use list_publications tool after deployment

Step 2: Deploy

1. Fork/clone this repo and push to GitHub

2. Go to Zeabur Dashboard

3. Create Project → Deploy from GitHub

4. Select your repo

5. Add Environment Variables (optional but recommended):

   Variable	Value	Required
   HASHNODE_PERSONAL_ACCESS_TOKEN	Your PAT	✅ Yes
   HASHNODE_PUBLICATION_ID	Your publication ID	❌ No (can use per-tool)

6. Click Deploy

Step 3: Get Your URL

After deployment, copy your URL:

https://your-app-name.zeabur.app/sse

🔌 Connect to AI Assistants

Claude Desktop / Cline Config:

{
  "mcpServers": {
    "hashnode": {
      "url": "https://your-app.zeabur.app/sse"
    }
  }
}

Config file locations:

• Claude Desktop:
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cline VSCode:
  • Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Cursor Config:

{
  "mcpServers": {
    "hashnode": {
      "url": "https://your-app.zeabur.app/sse"
    }
  }
}

📖 Usage Examples

First Time Setup

"Test my Hashnode connection"

"List my publications to see their IDs"

Publishing Articles

With default publication (env var set):

"Publish an article titled 'Getting Started with Python' 
with content '# Introduction\n\nPython is great...' 
and tags python, tutorial, beginners"

With specific publication ID:

"Publish to publication ID 'abc123' an article titled 'Advanced GraphQL' 
with tags graphql, api, content: '## GraphQL Tips\n\nHere are tips...'"

With cover image:

"Create a draft titled 'My Post' with cover image 
https://example.com/image.png and tags technology"

Managing Articles

"List my last 20 articles"

"Get article details for post ID 'post_id_here'"

"Update article 'post_id_here' with new title 'Updated Title'"

"Delete article 'post_id_here'"

Discovery

"Search for articles about 'machine learning'"

"Get articles by username 'john_doe'"

"Get publication details for host 'blog.hashnode.dev'"

🔧 Tool Parameters Reference

Common Parameters

Most article tools accept these parameters:

Parameter	Type	Required	Description
title	string	✅	Article title
content_markdown	string	✅	Article content in Markdown
subtitle	string	❌	Optional subtitle
tags	string[]	❌	Array of tag names (auto-converted to lowercase-slug)
cover_image_url	string	❌	URL for cover image
publication_id	string	⚠️	Required if env var not set

Tool-Specific Parameters

update_article:

• post_id (required) - Article ID to update

delete_article:

• post_id (required) - Article ID to delete

get_article:

• post_id (required) - Article ID to fetch

get_user_articles:

• username (required) - Hashnode username
• page (optional) - Page number, default 1

search_articles:

• query (required) - Search query
• limit (optional) - Results to return (1-20), default 10

list_my_articles:

• limit (optional) - Number of articles (1-50), default 10
• publication_id (optional) - Override default publication

get_publication:

• host (required) - Publication host/domain

⚠️ Error Messages & Fixes

"Publication ID is required"

Fix: Either:

1. Set HASHNODE_PUBLICATION_ID env var in Zeabur, OR
2. Pass publication_id parameter to the tool

"Authentication failed"

Fix: Check your HASHNODE_PERSONAL_ACCESS_TOKEN is correct and not expired.

"Tag format invalid"

Fix: Tags are auto-converted, but avoid special characters. Use simple names like "python", "web-development".

"Session not found"

Fix: The MCP session expired. Try the request again.

🐛 Troubleshooting

Connection Issues

1. Check Zeabur logs for startup errors
2. Verify HASHNODE_PERSONAL_ACCESS_TOKEN is set
3. Test with test_connection tool first

400 Errors on Publish

Usually means:

• Invalid tag format (fixed automatically now)
• Missing required fields
• Invalid publication ID

Check the error message - it now includes specific fix instructions!

📁 Project Structure

hashnode-mcp-zeabur/
├── server.js           # Main MCP server (10 tools)
├── package.json        # Node dependencies
├── Dockerfile          # Docker image for Zeabur
├── zeabur.yaml         # Zeabur deployment config
├── .env.example        # Environment template
└── README.md           # This file

🔐 Security Best Practices

1. Never commit .env file - It's in .gitignore
2. Use Zeabur's encrypted variables - They store secrets securely
3. Rotate PAT regularly - Regenerate in Hashnode settings if compromised
4. Restrict publication access - Only give necessary permissions

📚 Useful Links

• Hashnode API Docs
• MCP Specification
• Zeabur Documentation

📄 License

MIT License - feel free to use for personal or commercial projects!

---

Made with ❤️ for the Hashnode community