Description

n8n Community Node: Mastodon


This community-maintained n8n node adds Mastodon API operations for statuses, accounts, timelines, media, polls, bookmarks, lists and administration. Supported operations and permissions vary by Mastodon server version and credential scope. This project is not an official n8n or Mastodon integration.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration & Credentials
• Usage Examples

– Example Workflow Files
– Post a Status
– Fetch Public Timeline
– Manage Lists

• Available Resources & Operations
• Testing
• Development & Contributing
• License
• References
• Security, Support and Audit

Features

• Dual Authentication: Supports both OAuth2 and token based authentication.
• Statuses: Create, delete, edit, search, favourite, boost (reblog), bookmark, and manage scheduled statuses.
• Accounts: Follow, unfollow, block, mute, view profiles, and manage relationships.
• Timelines: Retrieve public, home, hashtag, list, and link timelines with advanced query options.
• Media: Upload and manage media attachments.
• Polls: Fetch poll data and cast votes.
• Bookmarks: Add and remove bookmarks from statuses.
• Lists: Create, update, and delete lists, and manage list membership.
• Notifications: Fetch and dismiss notifications.
• Administration: Admin level endpoints for reports, retention metrics, cohorts, and more.
• Enhanced Error Handling: Type safe handling with detailed error messages and automatic retry logic.
• Security-focused transport: Restricts credential-bearing requests to the configured instance origin, disables redirects, isolates authenticated GET caches and avoids automatic retries for writes. See Security policy for limitations.
• Customizable: Uses query parameters and additional fields for fine grained control.

Prerequisites

• Node.js v22 or v24 LTS for development (tested by CI)
• pnpm v10.33.0 (Corepack recommended for contributors)
• A self hosted n8n instance

Installation

From your n8n project root:
pnpm install n8n-nodes-the-mastodon
or with npm:
npm install n8n-nodes-the-mastodon

Note: pnpm is the single supported package manager for repository development and lockfile updates. npm users can install the published package in their n8n environment; do not regenerate a second lockfile in this repository.

Build the image with or without the plugin

The Dockerfiles in this repository support a safe multi stage build with optional plugin installation.

Usage patterns:

• Build with plugin: Provide the tarball through --build-arg and build the final-plugin target. The tarball must be in the build context (for example, the repository root), or use a path relative to the build context.

docker build --target final-plugin --build-arg PLUGIN_TARBALL=n8n-nodes-the-mastodon-0.0.1.tgz -t n8n-with-plugin .

• Local development using the dev Dockerfile (no plugin):

docker build -f Dockerfile.dev -t n8n-dev:plain .

• Local development with plugin:

docker build -f Dockerfile.dev --target final-plugin --build-arg PLUGIN_TARBALL=n8n-nodes-the-mastodon-0.0.1.tgz -t n8n-dev:plugin .

Notes:

• The plugin tarball is used only when you explicitly build the final-plugin target. Default builds with no target do not install a plugin.
• This approach works across common Docker installations and does not depend on BuildKit specific optional mounts. If you prefer BuildKit mounts, the older instructions are still in Git history, but the recommended path is the --target flow above.

After installation, n8n should detect the node automatically. Restart your n8n instance if it is already running.

Configuration & Credentials

The Mastodon node supports two authentication methods.

Method 1: Token based Authentication (recommended for simplicity)

Token based authentication is simpler to set up and works well for personal use or cases where OAuth2 flow is not required.

1. In your Mastodon instance, go to Settings > Development and create a new application.
– Name: for example, n8n
– Scopes: select read, write, and push as needed
– After creation, copy the Access Token from the application details

2. In n8n:
– Go to Credentials > New > Mastodon Access Token API
– Fill in:
– Mastodon Instance URL: https://mastodon.social (or your custom instance)
– Access Token: from step 1
– Save the credential

3. In your Mastodon node:
– Select Token as the Authentication Type
– Choose your saved token credential

Method 2: OAuth2 Authentication (required for authentication operations)

OAuth2 is required when you need authentication specific operations or want users to authorize through the standard OAuth flow.

1. In your Mastodon instance, go to Settings > Development and create a new application.
– Name: for example, n8n
– Redirect URI: http://localhost:5678/rest/oauth2-credential/callback
– Scopes: select read, write, and push as needed
– Note the Client ID and Client Secret

2. In n8n:
– Go to Credentials > New > Mastodon OAuth2 API
– Fill in:
– Instance URL: https://mastodon.social (or your custom instance)
– Client ID: from step 1
– Client Secret: from step 1
– Scope: read write push
– Save and click Connect, then authorize when prompted

3. In your Mastodon node:
– Select OAuth2 as the Authentication Type
– Choose your saved OAuth2 credential

Note: Authentication resource operations such as managing OAuth applications, creating or updating OAuth client apps, rotating client secrets, managing redirect URIs, revoking OAuth consent, and listing registered OAuth scopes require OAuth2 credentials. They do not work with token based authentication.

Note about deprecated scopes and server compatibility

Some Mastodon instances have deprecated or removed scopes such as follow and, in some configurations, may not accept push. If you see an error like this:

The requested scope is invalid, unknown, or malformed.

The authorization URL is likely requesting scopes that the server does not support. If that happens, you can:

• Edit the credential Scope value to request only read write before starting the Connect flow.
• Or, after the Connect URL opens, remove unsupported scopes from the scope query parameter (for example, change read write follow push to read write) and continue.

When available, the node tries to prefer currently granted scopes to avoid requesting deprecated or unsupported scopes automatically.

Usage Examples

Example Workflow Files

The repository includes ready to import n8n workflows under examples/:

• examples/Comprehensive Mastodon Test Workflow.json

– Comprehensive compatibility run in safe mode
– Focuses on read operations and reversible write operations with cleanup
– Recommended default for validating credentials, connectivity, and core functionality with lower risk

• examples/Comprehensive Mastodon Test Workflow.safe.json

– Same safe mode workflow as above, provided as an explicit safe variant
– Useful if you want to keep a safe profile while also maintaining a separate full mode file

• examples/Comprehensive Mastodon Test Workflow.full.json

– Full coverage workflow for advanced testing
– Includes additional admin/auth and higher impact operations, including profile deletion operations
– Use only in controlled test environments and test accounts

• examples/Mastodonexampleworkflow.json

– Minimal practical example: create a status, inspect context, add and remove a bookmark, then delete the status
– Good starting point for learning create and cleanup patterns

• examples/Mastodonnodetemplate.json

– Reusable template pattern with token auth and safe, reversible flows
– Demonstrates timeline fetch, search, follow/unfollow tag, and create/delete list in one pipeline

Import any file in n8n through Workflows -> Import from File.

Post a Status

1. Add a Mastodon node.
2. Set Resource to Status and Operation to Create.
3. Enter the Status text, and optionally add attachments or additional parameters.

- name: Post Status
  type: n8n-nodes-community/n8n-nodes-the-mastodon:Mastodon
  parameters:
    resource: status
    operation: create
    status: 'Hello from n8n and Mastodon!'
    additionalFields:
      visibility: 'public'

Fetch Public Timeline

• Resource: Timeline
• Operation: Public
• Use Additional Fields to filter local, remote, only_media, or paging parameters

- name: Get Public Timeline
  type: n8n-nodes-community/n8n-nodes-the-mastodon:Mastodon
  parameters:
    resource: timeline
    operation: public
    additionalFields:
      limit: 20
      local: true

Manage Lists

• Create List:

– Resource: Lists
– Operation: createList
– Set title and optional replies_policy

• Add Account:

– Resource: Lists
– Operation: addAccountsToList
– Set listId and accountIds

- name: Create and Update List
  type: n8n-nodes-community/n8n-nodes-the-mastodon:Mastodon
  parameters:
    resource: lists
    operation: createList
    title: 'My Favorite Authors'
name: Add Accounts
  type: n8n-nodes-community/n8n-nodes-the-mastodon:Mastodon
  parameters:
    resource: lists
    operation: addAccountsToList
    listId: '12345'
    accountIds:
      - '42'
      - '99'

Available Resources & Operations

| Resource | Operations |
| ————- | ——————————————————————————————————————————— |
| Status | create, delete, edit, search, favourite, unfavourite, boost, unboost, bookmark, removeBookmark, view, viewEditHistory, viewSource |
| Account | follow, unfollow, block, mute, unmute, verifyCredentials, viewProfile, getFollowers, getFollowing, searchAccounts |
| Timeline | public, hashtag, home, list, link |
| Bookmarks | getBookmarks, addBookmark, removeBookmark |
| Favourites | favourite, unfavourite |
| Lists | getLists, getList, createList, updateList, deleteList, getAccountsInList, addAccountsToList, removeAccountsFromList |
| Media | upload, update, delete, get (and more) |
| Polls | getPoll, votePoll |
| Notifications | getAll, dismiss |
| Reports | listReports, create, resolveReport |
| Retention | viewStatistics |
| Markers | get, save |
| … | (see full properties in code) |

For a full list of fields and parameter descriptions, see the code under nodes/Mastodon/*.

Testing

Automated tests are provided with Jest.

Install dev dependencies
pnpm install
Run tests
pnpm test
Or using the Makefile
make test

Test files are in tests, covering each resource and operation. The suite includes:

• Unit tests for API request handling
• Resource specific operation tests (accounts, statuses, timelines, and others)
• Rate limiting and queue management tests
• Error handling and retry logic tests
• URL truncation and extraction tests

Development & Contributing

Contributions are welcome. Please follow our LICENSE.md for details.

References

• Mastodon API Docs:
• n8n Community Nodes Docs:
• OAuth2 Setup Guide:

Quick verification (contributors)

corepack enable
pnpm install --frozen-lockfile
pnpm verify  # ESLint, Jest, build

CI verifies supported Node.js LTS versions. Runtime PKCE is generated with built-in Node.js cryptography; the published package has no direct third-party runtime dependencies. Only the latest published package release is supported for security fixes. Dependency upgrades are reviewed against pnpm-lock.yaml and CI; see AUDIT.md.

Safety notes

• Connect to the Mastodon instance configured in your credential. If you set the optional node URL, it must have the same origin as that credential.
• Mastodon API calls carrying credentials do not follow HTTP redirects. A redirect error may require correcting the instance URL.
• The repository includes destructive test workflows; only import the .full.json variants into a disposable instance and a dedicated test account.
• Report potential vulnerabilities privately using SECURITY.md. Never post tokens or private user content in public issues.

Validation scope

Every pull request runs a Node.js 22 and 24 matrix with a frozen pnpm install, ESLint, Jest and the production build. CI also smoke-builds the Docker images and checks the configured unprivileged runtime user. These are mocked unit tests, not live Mastodon OAuth, media-upload or administration integration tests.

All development Compose files bind to 127.0.0.1:5678 for local use. Example Docker images are pinned to n8n 2.46.6 and run as node. Operators upgrading n8n should read the release notes, back up workflow data and credentials, and test a disposable instance before changing the image tag; see 

Security, Support and Audit

Follow SECURITY.md for private vulnerability disclosure, SUPPORT.md for troubleshooting and AUDIT.md for the second-pass findings and unresolved risks. Do not include real credentials or private Mastodon content in public issues or PRs.

Architecture and contributing

See ARCHITECTURE.md for request scheduling, account-scoped caching and retry behavior; AUDIT.md for remediation status and residual risks; SECURITY.md for private vulnerability reporting; SUPPORT.md for troubleshooting; and CONTRIBUTING.md for a reproducible development and dependency-update workflow.