Skip to main content
Glama

NodeLoc MCP

English · 中文


English

An MCP (Model Context Protocol) server for the NodeLoc community (TypeScript). It lets any MCP-compatible AI client — Claude Desktop, Cursor, Cherry Studio, Cline, … — work with the forum through natural language: browse/post topics, private messages, likes/bookmarks/polls, nested communities (nodes), chat, daily check-in, red envelopes, energy-point rewards, the official payment API, knowledge-base lookup, and miniprogram CLI operations.

42 tools in total; tool descriptions are in English. Works with any MCP client over stdio.

Feature groups

Group

Tools

Account

get_current_user

Browsing

list_latest_topics list_top_topics read_topic list_category_topics get_site_info get_user_profile get_user_summary search_users

Notifications / PM

list_notifications mark_notifications_read list_private_messages send_private_message

Writing

create_topic reply_to_topic

Interaction

like_post unlike_post bookmark_post vote_poll unvote_poll

Nodes

list_nodes list_node_topics join_node leave_node create_node check_node_slug

Chat

get_chat_messages get_chat_thread_messages send_chat_message mark_chat_read

Energy

checkin create_red_envelope give_reward get_points_history get_points_scores

Payment (official API)

payment_create payment_query payment_transfer

Knowledge base

docs_list_pages docs_get_page docs_search

Miniprograms

apps_cli

Requirements & build

Requires Node.js ≥ 20 (uses fetch and headers.getSetCookie()).

npm install
npm run build        # bundles everything into a single dist/index.js (~760 KB)

dist/index.js is self-contained — to distribute, ship this one file plus a Node runtime; no npm install needed on the target machine.

Configuration (environment variables)

Variable

Required

Description

NODELOC_USERNAME

✅

Forum username or email

NODELOC_PASSWORD

✅

Forum password (only used to obtain a cookie session; the session is stored in a local file)

NODELOC_BASE_URL

Default https://www.nodeloc.com

NODELOC_TIMEZONE

Default Asia/Shanghai

NODELOC_LOCALE

Default zh-CN (used by the check-in request header)

NODELOC_SECOND_FACTOR_METHOD

2FA: 0 none / 1 SMS / 2 TOTP, default 0

NODELOC_PAYMENT_ID

payment tools

Payment app ID (pay_xxx), apply at payment/applications (TL1+, admin approval)

NODELOC_PAYMENT_TOKEN

payment tools

Payment app token (tk_xxx)

NODELOC_APPS_CLI

apps tools

nodeloc-apps CLI path, defaults to PATH lookup

NODELOC_DATA_DIR

Session/docs cache directory, default ~/.nodeloc-mcp

Note: NodeLoc has disabled the Discourse User-Api-Key flow, so this server uses cookie-session auth (same as the official app): POST /session login → session persisted locally → automatic re-login on expiry.

MCP client example

{
  "mcpServers": {
    "nodeloc": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "NODELOC_USERNAME": "your_username",
        "NODELOC_PASSWORD": "your_password"
      }
    }
  }
}

Project structure

src/
├── config.ts        # environment configuration
├── client.ts        # HTTP client + cookie-session auth (Cloudflare detection, auto re-login, session persistence)
├── index.ts         # MCP entry, registers 42 tools (English descriptions)
└── tools/
    ├── forum.ts     # topics/posts/PMs/interactions/nodes/chat
    ├── energy.ts    # check-in/red envelopes/rewards/points
    ├── payment.ts   # official payment API (HMAC-SHA256 signing)
    ├── docs.ts      # knowledge base (llms.txt index + Markdown cache)
    └── apps.ts      # nodeloc-apps CLI wrapper

Known limitations

  • Miniprogram development access requires a manual admin approval and cannot be automated; apps_cli only wraps an existing CLI (interactive commands like login must be run once in a terminal yourself)

  • OAuth (docs.nodeloc.com) is an outbound service — "log in to third-party sites with your NodeLoc account" — unrelated to this server's forum auth, not included

  • The check-in endpoint enforces nonce + timestamp anti-cheat validation; write operations are rate-limited by the forum, and server errors are passed through

  • MessageBus real-time long-polling is not implemented (of limited use in a request-driven MCP model)

References


Related MCP server: @damusix/buffer-mcp

中文

NodeLoc 论坛的 MCP(Model Context Protocol)服务器(TypeScript 实现),让 AI 助手直接操作论坛:浏览/发帖/私信/点赞/投票、节点社区、聊天、每日签到、红包、打赏、积分查询、官方支付 API、知识库检索、小程序 CLI 操作。

共 42 个工具,工具描述为英文,适用于任意 MCP 客户端(Claude Desktop、Cursor、Cherry Studio、Cline 等)。

功能一览

分组

工具

账号

get_current_user

浏览

list_latest_topics list_top_topics read_topic list_category_topics get_site_info get_user_profile get_user_summary search_users

通知/私信

list_notifications mark_notifications_read list_private_messages send_private_message

写作

create_topic reply_to_topic

互动

like_post unlike_post bookmark_post vote_poll unvote_poll

节点社区

list_nodes list_node_topics join_node leave_node create_node check_node_slug

聊天

get_chat_messages get_chat_thread_messages send_chat_message mark_chat_read

能量

checkin create_red_envelope give_reward get_points_history get_points_scores

支付(官方 API)

payment_create payment_query payment_transfer

知识库

docs_list_pages docs_get_page docs_search

小程序

apps_cli

安装与构建

要求 Node.js ≥ 20(用了 fetch 和 headers.getSetCookie())。

npm install
npm run build        # 打包成单文件 dist/index.js(约 760 KB,含全部依赖)

打包后的 dist/index.js 是自包含的单文件——分发给别人时只需这一个文件 + Node 运行时,无需 npm install。

配置(环境变量)

变量

必填

说明

NODELOC_USERNAME

✅

论坛用户名或邮箱

NODELOC_PASSWORD

✅

论坛密码(仅用于登录换取 Cookie 会话,会话仅存本地文件)

NODELOC_BASE_URL

默认 https://www.nodeloc.com

NODELOC_TIMEZONE

默认 Asia/Shanghai

NODELOC_LOCALE

默认 zh-CN(签到请求头用)

NODELOC_SECOND_FACTOR_METHOD

2FA 方式:0 无 / 1 短信 / 2 TOTP,默认 0

NODELOC_PAYMENT_ID

支付工具需要

支付应用 ID(pay_xxx),申请入口(TL1+,需审批)

NODELOC_PAYMENT_TOKEN

支付工具需要

支付应用 token(tk_xxx)

NODELOC_APPS_CLI

小程序工具需要

nodeloc-apps CLI 路径,默认从 PATH 查找

NODELOC_DATA_DIR

会话与文档缓存目录,默认 ~/.nodeloc-mcp

注:NodeLoc 站点已禁用 Discourse User-Api-Key,因此采用 Cookie 会话鉴权(与官方 App 相同):POST /session 登录 → 会话持久化到本地 → 过期自动重新登录。

MCP 客户端接入示例

{
  "mcpServers": {
    "nodeloc": {
      "command": "node",
      "args": ["/绝对路径/dist/index.js"],
      "env": {
        "NODELOC_USERNAME": "your_username",
        "NODELOC_PASSWORD": "your_password"
      }
    }
  }
}

项目结构

src/
├── config.ts        # 环境变量配置
├── client.ts        # HTTP 客户端 + Cookie 会话鉴权(Cloudflare 检测、自动重登、会话持久化)
├── index.ts         # MCP 入口,注册 42 个工具(英文描述)
└── tools/
    ├── forum.ts     # 主题/帖子/私信/互动/节点/聊天
    ├── energy.ts    # 签到/红包/打赏/积分
    ├── payment.ts   # 官方支付 API(HMAC-SHA256 签名)
    ├── docs.ts      # 知识库(llms.txt 索引 + Markdown 缓存)
    └── apps.ts      # nodeloc-apps CLI 封装

已知边界

  • 小程序开发权限需人工向管理员申请,无法自动化;apps_cli 仅封装已有 CLI(login 等交互式命令需先在终端手动执行一次)

  • OAuth(docs.nodeloc.com 的 OAuth 对接)是"用 NodeLoc 账号登录第三方平台"的对外服务,与本 MCP 的论坛鉴权无关,未纳入

  • 签到接口有 nonce + 时间戳反作弊校验;写操作受论坛频率限制,工具会透传服务端错误

  • MessageBus 实时长轮询未实现(MCP 按需调用模型下意义有限)

参考

Available Tools

42 tools
apps_cliA

Run an official nodeloc-apps CLI command for in-site miniprograms, e.g. 'init my-app', 'playtest', 'submit'. Requires the CLI installed and logged in (interactive login must be done once in a terminal yourself). cwd: project directory to run in.

Inputs: command (required), cwd.

bookmark_postC

Bookmark a post.

Inputs: post_id (required).

checkinA

Perform the daily check-in and collect energy points. Once per day; a repeated call returns the 'already checked in' result from the server.

Inputs: no named parameters.

check_node_slugA

Check whether a node slug is available before creating a node.

Inputs: slug (required).

create_nodeC

Create a new node (nested community). color is an optional hex color.

Inputs: name (required), slug (required), description (required), parent_category_id (required), +1 more.

create_red_envelopeA

Create a red envelope in a topic: total_points energy split into total_count shares, claimable by users who reply.

Inputs: topic_id (required), total_count (required), total_points (required).

create_topicA

Create a new topic. raw is Markdown; category_id from get_site_info.

Inputs: raw (required), title (required), category_id (required).

docs_get_pageA

Fetch a knowledge-base page as Markdown. page can be a full URL, a path like 'energy/checkin', or a title fragment from docs_list_pages.

Inputs: page (required).

docs_list_pagesA

List all pages of the NodeLoc knowledge base (title, url, description).

Inputs: no named parameters.

get_chat_messagesB

Fetch messages of a chat channel (paginated).

Inputs: channel_id (required), page_size.

get_chat_thread_messagesC

Fetch messages of a chat thread inside a channel.

Inputs: thread_id (required), channel_id (required), page_size.

get_current_userA

Get the currently logged-in NodeLoc user (id, username, trust level, unread notification counts). Logs in automatically if needed.

Inputs: no named parameters.

get_points_historyA

Get energy points income/expense history (defaults to the logged-in user).

Inputs: username.

get_points_scoresA

Get energy points score breakdown (defaults to the logged-in user).

Inputs: username.

get_site_infoA

Get site configuration: categories (id/name/slug) etc. Anonymous.

Inputs: no named parameters.

get_user_profileA

Get a user's public profile (trust level, bio, stats). Anonymous.

Inputs: username (required).

get_user_summaryB

Get a user's activity summary (posts, likes, badges). Anonymous.

Inputs: username (required).

give_rewardB

Tip energy points to the author of a post.

Inputs: amount (required), post_id (required), note.

join_nodeC

Join a node (nested community).

Inputs: node_id (required).

leave_nodeC

Leave a node (nested community).

Inputs: node_id (required).

like_postC

Like a post.

Inputs: post_id (required).

list_category_topicsB

List topics in a category. filter is typically 'latest' or 'top'. Anonymous.

Inputs: slug (required), category_id (required), page, filter.

list_latest_topicsA

List latest topics on the forum homepage. Anonymous; page starts at 0.

Inputs: page.

list_nodesA

List all nested communities (nodes) and my memberships.

Inputs: no named parameters.

list_node_topicsB

List topics inside a node (nested community).

Inputs: slug (required), node_id (required), page, sort.

list_notificationsA

List notifications for the logged-in user (mentions, replies, likes, PMs).

Inputs: no named parameters.

list_private_messagesA

List private-message topics of a user (defaults to the logged-in user).

Inputs: username.

list_top_topicsA

List top/trending topics. Anonymous.

Inputs: no named parameters.

mark_chat_readA

Mark a chat channel as read up to a message id.

Inputs: channel_id (required), message_id (required).

mark_notifications_readA

Mark all notifications as read, or a single one when notification_id is given.

Inputs: notification_id.

payment_createA

Create a payment request (official Payment API). Returns a payment_url the buyer must open to pay. order_id is your unique order reference.

Inputs: amount (required), order_id (required), description (required).

payment_queryC

Query the status of a payment transaction (official Payment API).

Inputs: transaction_id (required).

payment_transferA

Transfer energy points from the payment-app owner to a user (official Payment API). to_user_id and to_username must refer to the same user. Sender pays a trust-level-based fee; idempotent per order_id.

Inputs: amount (required), order_id (required), to_user_id (required), to_username (required).

read_topicA

Read a topic with its posts (trimmed HTML bodies). Anonymous.

Inputs: topic_id (required).

reply_to_topicB

Reply to a topic (Markdown body). Optionally reply to a specific post number.

Inputs: raw (required), topic_id (required), reply_to_post_number.

search_usersA

Search users by name/username, e.g. to resolve @mentions or PM recipients.

Inputs: term (required).

send_chat_messageB

Send a chat message to a channel, optionally into a thread.

Inputs: message (required), channel_id (required), thread_id.

send_private_messageC

Send a private message. recipients: comma-separated usernames.

Inputs: raw (required), title (required), recipients (required).

unlike_postB

Remove a like from a post.

Inputs: post_id (required).

unvote_pollC

Retract a poll vote.

Inputs: post_id (required), poll_name (required).

vote_pollC

Vote in a poll attached to a post. options: the chosen option values.

Inputs: options (required), post_id (required), poll_name (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 42 tools

    Disambiguation4/5

    Most tools target distinct actions and resources, with clear boundaries between topic listing, node membership, chat, points, and payments. A few pairs like get_user_profile vs get_user_summary or list_latest_topics vs list_top_topics could cause minor hesitation, but descriptions generally make the differences clear.

    Naming Consistency3/5

    The set uses recognizable patterns for many groups (list_*, get_*, create_*, payment_*, docs_*), but mixes read verbs inconsistently: get_current_user, list_latest_topics, read_topic. Some actions are unprefixed like checkin, and payment tools use prefix-noun while most others use verb-noun, so the naming is readable but not uniform.

    Tool Count2/5

    With 42 tools, the server exceeds the threshold where a tool set feels heavy and hard to navigate. The broad domain explains part of the size, but many tools are granular variants that could be consolidated without losing clarity.

    Completeness3/5

    The server covers a wide range of community features: topics, posts, PMs, nodes, chat, points, payments, and docs. However, there are notable gaps such as no topic search, no update/delete for topics or posts, no node update/delete, and no chat channel discovery or management, leaving important workflows incomplete.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers