M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
H

HackMD MCP Server

Community
A Model Context Protocol server for integrating HackMD's note-taking platform with AI assistants.
How to install ↓ Compare GitHub source repository ↗
Category
Collaboration #16 of 55
Stars
★ 68 Popular
Transport
stdio (local process) · Streamable HTTP
Runtime
Node.js 18+ · Docker
Credentials
API key / credential required
License
MIT
Last commit
Tools
12
58FMRS · C

This server is focused on HackMD note management, implementing CRUD operations on notes, teams, history, and user profile. Installation is straightforward, and it supports multiple transports, making it suitable for integration into MCP-capable AI clients. Security relies on user's care in protecting the API token.

Strongest · Documentation 15/20 Weakest · Reliability 7/20

Reliability
7/20
Security and permissions
10/20
Maintenance
12/20
Documentation
15/20
Setup experience
14/20
Why each score
Reliability 7/20
Evidence is limited to the README and server.json; no source code, tests, or CI results were supplied. The README claims stdio/HTTP transports, lists tools, and gives examples, but the MCP init handshake, tool-list consistency with real behavior, and error/dependency controllability cannot be verified. Per static calibration, unverified happy paths with thin testing and edge-case handling cannot score high; thus 7.
Security and permissions 10/20
The token is a required secret environment variable, with optional HTTP-header override and a documented warning to protect the HTTP endpoint. An optional ALLOWED_HACKMD_API_URLS whitelist is described. However, source code is absent, so we cannot confirm secrets are never logged or sent to unintended hosts; HTTP transport is not authenticated by default, and destructive tools such as delete_note/delete_team_note have no documented confirmation step. Main risks are visible but least-privilege and confirmation/scoping are incomplete, so 10.
Maintenance 12/20
The repository is not archived, is MIT-licensed, shows version 1.5.7, and publishes npm, OCI, and MCPB artifacts; README includes Docker and MCPB workflows. But there is no evidence of commit recency, release dates, dependency-update policy, or issue responsiveness in the supplied material. Stars and open-issue counts alone neither prove nor disprove sustained maintenance, so a middling score is appropriate.
Documentation 15/20
The README covers installation, authentication, environment variables, HTTP headers, token acquisition, tool lists, examples, local development, MCP Inspector, Docker, MCPB, and security notices, giving good layered documentation. Deductions are made for missing per-tool input schemas/parameters, error handling, API limits/cost, troubleshooting, and documented limitations; some cloud-deployment claims are unverifiable from the supplied evidence.
Setup experience 14/20
Setup is clear and short: an npx command with env block for mcp.json / claude_desktop_config.json, plus Docker, MCPB, and cloud-platform options. Environment variable descriptions and an Inspector debug path help users connect. However, there is no real CI/test execution evidence proving a clean start, and troubleshooting for mainstream client configuration issues is absent; static calibration caps this dimension at 15, so 14 is returned.

Static review · not runListed 2026-08-07

Read the FMRS scoring method →

Fit and risk

What it can accessUses the networkChanges third-party account data

Best for

  • Developers who want to integrate HackMD note management into AI workflows
  • Individuals or teams who prefer natural language interaction with their notes
  • Users who need cloud deployment of MCP servers

Not for

  • Not suitable for users without a HackMD API token
  • Not suitable for offline access to notes (server depends on network API)
  • Not for scenarios requiring advanced collaboration features like real-time co-editing, as the server provides mainly CRUD operations

Required permissions

  • Requires HackMD API token (HACKMD_API_TOKEN) to authenticate all operations
  • Server can read and modify user profile, notes, teams, history, etc., depending on token permissions

Risks and side effects

  • API token leakage could lead to unauthorized account access; never commit it to version control
  • For HTTP transport, if the server is hosted without endpoint protection, anyone could use your token
  • Server modifies user data (create, update, delete notes); confirm before operations

Setup

Before you start

Runtime：Node.js 18+ · Docker

HACKMD_API_TOKEN requiredsecret Required HackMD API token for all API operations; create one at https://hackmd.io/settings#api via 'Create API Token'.
Other optional settings (3)
HACKMD_API_URL optional Optional HackMD API URL, defaults to https://api.hackmd.io/v1.
ALLOWED_HACKMD_API_URLS optional Optional comma-separated allowlist of HackMD API URLs for the HTTP transport server; only the default URL is allowed if unset.
PORT optional Optional port for the HTTP transport server, defaults to 8081.
  1. Ensure Node.js 18+ is installed.
  2. Add the configuration above to your MCP client config file (e.g., mcp.json or claude_desktop_config.json).
  3. Restart your MCP client.
  4. Use the tools to interact with HackMD.
claude_desktop_config.json 
{
  "mcpServers": {
    "hackmd": {
      "command": "npx",
      "args": ["-y", "hackmd-mcp"],
      "env": {
        "HACKMD_API_TOKEN": "your_api_token"
      }
    }
  }
}

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json
{
  "servers": {
    "hackmd": {
      "command": "npx",
      "args": [
        "-y",
        "hackmd-mcp"
      ],
      "env": {
        "HACKMD_API_TOKEN": "your_api_token"
      }
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal
claude mcp add hackmd -e HACKMD_API_TOKEN=your_api_token -- npx -y hackmd-mcp

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

After adding the server to your MCP client config and restarting it, check that tools like get_user_info and list_user_notes appear in the client's tool list, then call get_user_info — a returned authenticated user profile confirms the connection works.

Troubleshooting

  1. Check that HACKMD_API_TOKEN is set correctly and not expired
  2. Verify network connectivity to HackMD API
  3. Inspect MCP client logs for error details
  4. For HTTP transport, ensure ALLOWED_HACKMD_API_URLS is configured correctly, otherwise requests may be rejected

Things to try

Once connected, you can ask your AI assistant things like:

  • Get my HackMD user profile information.
  • Please list all my notes.
  • Create a new note titled 'Meeting Notes' with discussion points as content.
  • Show me all the teams I'm part of and list the notes in the first team.

Tools 12

get_user_info read-only
Get information about the authenticated user
list_teams read-only
List all teams accessible to the user
get_history read-only
Get user's reading history
list_team_notes read-only
List all notes in a team
create_team_note writes
Create a new note in a team
update_team_note writes
Update an existing note in a team
delete_team_note destructive
Delete a note in a team
list_user_notes read-only
List all notes owned by the user
Show 4 more tools
get_note read-only
Get a note by its ID
create_note writes
Create a new note
update_note writes
Update an existing note
delete_note destructive
Delete a note

Use cases

Quickly create and manage HackMD notes via an AI assistant
Ask AI to list and organize user notes and team notes
Automate note updates and archiving in team collaboration

Supported clients

Claude Desktop

Listed from the project's documentation, not tested by this site.

Overview

This is a Model Context Protocol (MCP) server that interfaces with the HackMD API, allowing LLM clients to access and interact with HackMD notes, teams, user profiles, and history data. It supports both STDIO and HTTP transports, and is cloud-deployment ready via platforms like Smithery.

Similar servers

Compare with other MCP servers

Source revision 38f6a4b67e2f Data synced 2026-10-11 Read the FMRS scoring method