AfdianToMarkdown

AfdianToMarkdown is a Go-based tool that can run in MCP (Model Context Protocol) mode to expose a read-only search and retrieval service over your downloaded Afdian content. It serves the locally downloaded dynamics (motions) and portfolios (albums) to AI assistants or clients via an HTTP MCP endpoint, or locally via stdio. In MCP mode, you don’t need cookies.json — the server provides access only to content already downloaded on disk, returning Markdown-formatted posts on request. The available tools include list_authors to enumerate downloaded authors, list_posts to list an author's posts, read_post to fetch a post in full Markdown, and search to perform a full-text search across downloaded documents. You can run the server in HTTP mode for remote access or in stdio mode for local integration with Claude Code or similar clients.

Prerequisites:

• A compiled AfdianToMarkdown binary (built from source or downloaded from releases).
• Go environment only if you plan to build from source.
• Optional: a data directory with downloaded content (motions and albums) if you intend to run MCP in read-only mode.

Installation steps:

1. Download or build the binary
   • Download prebuilt binaries from the project's releases page and place the executable in your desired directory.
   • Or build from source (requires Go):

git clone https://github.com/PhiFever/AfdianToMarkdown.git
cd AfdianToMarkdown
go build -o AfdianToMarkdown

2. Run in MCP HTTP mode (remote access) as described below in the usage section.
3. If you intend to use stdio mode with Claude Code, ensure the binary is accessible and proceed to configure your Claude integration (see MCP section).

Notes:

• In MCP mode, cookies.json is not required because the server reads only local, already-downloaded data.
• The first time you launch in HTTP mode, ensure the chosen port is open in your firewall if you plan remote access.

Tips and common issues:

• If you see issues with downloads or domain handling, ensure you have the latest binary and that your data dir contains motions/ and albums/ as expected by the MCP API.
• In HTTP mode, you can specify --addr to bind to a specific interface, e.g., 0.0.0.0:8080 for public access or 127.0.0.1:9090 for localhost only.
• Use the --dir option to point to a specific data directory if your content lives outside the default location.
• The MCP endpoints provide read-only access to content; attempting to modify content via MCP is not supported.
• If your environment uses Windows, wrap the executable path in quotes if there are spaces, and consider using the Windows-specific path syntax in the command field.