📌Overview

Purpose: To provide a Model Context Protocol (MCP) server that facilitates interaction with the HackMD API for managing notes and user information.

Overview: The HackMD MCP Server enables AI assistants to perform a variety of operations related to HackMD user accounts, including note management and team collaboration. It streamlines the integration of HackMD capabilities into AI applications, allowing for efficient communication and handling of notes.

Key Features:

User Interaction: Provides APIs to get user information and reading history, enabling a personalized experience when managing notes.
Notes Management: Allows for creating, reading, updating, and deleting notes, giving users comprehensive control over their content.
Team Collaboration: Supports operations on team notes, which facilitates collaborative efforts and sharing within teams.
Debugging Tools: Includes an MCP Inspector for testing and debugging the server, ensuring reliable functionality before deployment.

HackMD MCP Server

The HackMD MCP Server enables interaction with the HackMD API and allows AI assistants to perform various operations such as retrieving user information, managing notes, and viewing read history.

Requirements

Node.js 18+
HackMD API token

Installation

Clone the repository and install dependencies:

git clone https://github.com/yuna0x0/hackmd-mcp.git
cd hackmd-mcp
bun install  # or use npm, yarn, pnpm

Configuration

Using a .env file

Create a .env file:
```
cp .env.example .env
```
Add your HackMD API token:
```
HACKMD_API_TOKEN=your_api_token
```

Using environment variables inline

Alternatively, provide the API token directly when running the server:

HACKMD_API_TOKEN=your_api_token bun start

You can get an API token from HackMD settings.

Usage

Start the MCP Server

Local installation:

bun start  # or use npm, yarn, pnpm

Using bunx (without cloning):

HACKMD_API_TOKEN=your_api_token bunx hackmd-mcp

Debugging with MCP Inspector

To test and debug the HackMD MCP server:

bun run inspector  # or use npm, yarn, pnpm

For alternative use with bunx:

bunx @modelcontextprotocol/inspector -e HACKMD_API_TOKEN=your_api_token bunx hackmd-mcp

Open your browser to the provided URL to access the MCP Inspector interface.

Using with Claude Desktop or other MCP clients

Add this server to your claude_desktop_config.json:

{
  "mcpServers": {
    "hackmd": {
      "command": "npx",
      "args": ["-y", "hackmd-mcp"],
      "env": {
        "HACKMD_API_TOKEN": "your_api_token"
      }
    }
  }
}

Restart Claude Desktop and use the tools to interact with your HackMD account.

Available Tools

User API

get_user_info: Get information about the authenticated user

User Notes API

list_user_notes: List all notes owned by the user
get_note: Get a note by its ID
create_note: Create a new note
update_note: Update an existing note
delete_note: Delete a note
get_history: Get user's reading history

Teams API

list_teams: List all teams accessible to the user

Team Notes API

list_team_notes: List all notes in a team
create_team_note: Create a new note in a team
update_team_note: Update an existing note in a team
delete_team_note: Delete a note in a team

Security Notice

This MCP server requires your HackMD API token in the .env file or as an environment variable. Keep this information secure and do not commit it to version control.

License

This project is licensed under the MIT License. See the LICENSE file for details.