{
  "markdown": "# HackMD MCP Server\n\nA Model Context Protocol (MCP) server that interfaces with the [HackMD API](https://hackmd.io/@hackmd-api/developer-portal), allowing LLM clients to access and interact with HackMD notes, teams, user profiles, and history data.\n\n## Features\n\n- Get user profile information\n- Create, read, update, and delete notes\n- Manage team notes and collaborate with team members\n- Access reading history\n- List and manage teams\n- **Dual transport support**: Both HTTP and STDIO transports\n- **Cloud deployment ready**: Support Smithery and other platforms\n\n## Requirements\n\n- Node.js 18+\n\n## Local Installation (STDIO Transport)\n\n1. Add this server to your `mcp.json` / `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"hackmd\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"hackmd-mcp\"],\n      \"env\": {\n        \"HACKMD_API_TOKEN\": \"your_api_token\"\n      }\n    }\n  }\n}\n```\n\nYou may also optionally set the `HACKMD_API_URL` environment variable if you need to use a different HackMD API endpoint.\n\n2. Restart your MCP client (e.g., Claude Desktop)\n3. Use the tools to interact with HackMD\n\n## Server Deployment (HTTP Transport)\n\n### Self-Hosting\nFollow the [Local Development](#local-development) instructions to set up the project locally, then run:\n```bash\npnpm run start:http\n```\nThis will start the server on port 8081 by default. You can change the port by setting the `PORT` environment variable.\n\n### Cloud Deployment\n\nYou can deploy this MCP server to any cloud platform that supports Node.js server applications.\n\nYou can also deploy via MCP platforms like [Smithery](https://smithery.ai/server/@yuna0x0/hackmd-mcp).\n\n## Configuration\n### Environment Variables (STDIO Transport and HTTP Transport server where host provides the config)\n\nWhen using the STDIO transport or hosting the HTTP transport server, you can pass configuration via environment variables:\n- `HACKMD_API_TOKEN`: HackMD API Token (Required for all operations)\n- `HACKMD_API_URL`: (Optional) HackMD API URL (Defaults to https://api.hackmd.io/v1)\n\nEnvironment variables applied only for the HTTP transport server:\n- `ALLOWED_HACKMD_API_URLS`: (Optional) A comma-separated list of allowed HackMD API URLs. The server will reject requests if the provide HackMD API URL is not in this list. If not set, only the default URL (https://api.hackmd.io/v1) is allowed.\n\n> [!CAUTION]\n> If you are hosting the HTTP transport server with token pre-configured, you should protect your endpoint and implement authentication before allowing users to access it. Otherwise, anyone can access your MCP server while using your HackMD token.\n\n### HTTP Headers (HTTP Transport where user provides the config)\n\nWhen using the HTTP transport, user can pass configuration via HTTP headers:\n- `Hackmd-Api-Token`: HackMD API Token (Required for all operations)\n- `Hackmd-Api-Url`: (Optional) HackMD API URL (Defaults to https://api.hackmd.io/v1)\n\nIf the user provides the token in the header, while the server also has `HACKMD_API_TOKEN` set, the header value will take precedence.\n\n### Get a HackMD API Token\n\nTo get an API token, follow these steps:\n\n1. Go to [HackMD settings](https://hackmd.io/settings#api).\n2. Click on \"Create API Token\".\n3. Copy the generated token and use it in your `.env` file or environment variables.\n\n## Available Tools\n\n### Profile Tools\n- **get_user_info**: Get information about the authenticated user\n\n### Teams Tools\n- **list_teams**: List all teams accessible to the user\n\n### History Tools\n- **get_history**: Get user's reading history\n\n### Team Notes Tools\n- **list_team_notes**: List all notes in a team\n- **create_team_note**: Create a new note in a team\n- **update_team_note**: Update an existing note in a team\n- **delete_team_note**: Delete a note in a team\n\n### User Notes Tools\n- **list_user_notes**: List all notes owned by the user\n- **get_note**: Get a note by its ID\n- **create_note**: Create a new note\n- **update_note**: Update an existing note\n- **delete_note**: Delete a note\n\n## Example Usage\n\n### Basic Note Management\n\n```\nCan you help me manage my HackMD notes?\n```\n\n### List Notes\n\n```\nPlease list all my notes.\n```\n\n### Create a New Note\n\n````\nCreate a new note with the title \"Meeting Notes\" and content:\n```\n# Meeting Notes\n\nDiscussion points:\n- Item 1\n- Item 2\n```\n````\n\n### Team Collaboration\n\n```\nShow me all the teams I'm part of and list the notes in the first team.\n```\n\n## Local Development\n\nThis project uses [pnpm](https://pnpm.io) as its package manager.\n\nClone the repository and install dependencies:\n\n```bash\ngit clone https://github.com/yuna0x0/hackmd-mcp.git\ncd hackmd-mcp\npnpm install\n```\n\n### Configuration\n\n1. Create a `.env` file by copying the example:\n```bash\ncp env.example .env\n```\n\n2. Edit the `.env` file and add your HackMD API token:\n```\nHACKMD_API_TOKEN=your_api_token\n```\n\n## Debugging with MCP Inspector\n\nYou can use the MCP Inspector to test and debug the HackMD MCP server:\n\n```bash\nnpx @modelcontextprotocol/inspector -e HACKMD_API_TOKEN=your_api_token npx hackmd-mcp\n\n# Use this instead when Local Development\npnpm run inspector\n```\n\nThen open your browser to the provided URL (usually http://localhost:6274) to access the MCP Inspector interface. From there, you can:\n\n1. Connect to your running HackMD MCP server\n2. Browse available tools\n3. Run tools with custom parameters\n4. View the responses\n\nThis is particularly useful for testing your setup before connecting it to MCP clients like Claude Desktop.\n\n## Docker\n\nPull from GitHub Container Registry:\n```bash\ndocker pull ghcr.io/yuna0x0/hackmd-mcp\n```\n\nDocker build (Local Development):\n```bash\ndocker build -t ghcr.io/yuna0x0/hackmd-mcp .\n```\n\nDocker multi-platform build (Local Development):\n```bash\ndocker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/yuna0x0/hackmd-mcp .\n```\n\n## MCP Bundles (MCPB)\n\nTo create an MCP Bundle for this server, run:\n```bash\npnpm run pack:mcpb\n```\n\n## Security Notice\n\nThis MCP server accepts your HackMD API token in the .env file, environment variable or HTTP header. Keep this information secure and never commit it to version control.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
  "bytes": 6218,
  "sha": "b33771f1884af111808a8b77ab6d0aa8c85bbb3d3d4865ae0a390351f0bf3df7",
  "repo_slug": "yuna0x0/hackmd-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yuna0x0_hackmd_mcp_75c3dc99/readme"
}