Markdown

You can connect to and manage your markdown articles through an MCP server that exposes a REST API and an MCP endpoint for AI agents. This setup lets you store, search, and semantically explore large collections of articles while controlling access with tokens and roles.

How to use

Connect your MCP-enabled client to the server to manage articles, folders, and embeddings. Use an access token with the appropriate scope to perform actions like listing, reading, creating, updating, or deleting articles. If you enable semantic search, you can perform vector-based queries to retrieve relevant chunks of article content. Your MCP client will interact with the server through the MCP endpoint to discover available tools and execute actions, while the REST API handles standard data operations.

How to install

Follow these concrete steps to set up the MCP Markdown Manager locally with containerized services and tokens for secure access.

# Prerequisites
# - Docker and Docker Compose
# - Bun runtime (for local development scripts)

# 1. Pull and run the MCP Markdown Manager container (for quick start)
docker run -d -p 8097:5000 \
  -e AUTH_TOKEN="your-secret-token-here" \
  -e MCP_SERVER_ENABLED="true" \
  -v $(pwd)/data:/data \
  ghcr.io/joelmnz/mcp-markdown-manager:latest

# 2. Generate an access token via the web UI (after login)
# Access the UI at http://localhost:8097 and login with the AUTH_TOKEN

# 3. Connect an MCP client
# Use the generated token in the Authorization header for MCP requests

Security and configuration notes

The system uses a two-tier authentication model: an admin token for web UI login and scoped access tokens for API/MCP operations. Tokens are prefixed with sk-md- to identify them clearly. Always prefer read-only tokens for monitoring and search integrations, and rotate tokens regularly. When deploying to production, serve the app over HTTPS behind a reverse proxy and monitor token usage via the last_used_at timestamps.

# Example environment variables
AUTH_TOKEN=your-admin-token
MCP_SERVER_ENABLED=true
DATA_DIR=/data
PORT=5000
BASE_URL=https://your-domain.com/md
SEMANTIC_SEARCH_ENABLED=false

{
  "mcpServers": [
    {
      "type": "http",
      "name": "markdown_mcp",
      "url": "http://localhost:8097/mcp",
      "args": []
    }
  ],
  "envVars": [
    {"name": "AUTH_TOKEN", "description": "Admin authentication token for web UI login", "required": true, "example": "your-admin-token"},
    {"name": "MCP_SERVER_ENABLED", "description": "Enable MCP server functionality", "required": true, "example": "true"},
    {"name": "DATA_DIR", "description": "Data directory for storage", "required": true, "example": "/data"}
  ]
}

Troubleshooting and notes

If port conflicts occur, verify that the default port is free and adjust your deployment accordingly. Check logs for errors related to authentication, token scopes, or database connectivity. For semantic search, ensure the embedding backend is running and correctly configured. If you need to revert to a baseline, restore from a backup of the data directory.

Notes on usage patterns

• Use the web UI to manage tokens and monitor access. - Use the MCP endpoint to invoke tools from AI agents. - When semantic search is enabled, index and query content by heading context for more precise results. - Import markdown articles via the import utility to populate the database with existing content.

Available tools

listArticles

List all articles with metadata.

listFolders

List folder structure and hierarchy.

searchArticles

Search articles by title.

multiSearchArticles

Batch search across articles.

readArticle

Read the full content of a single article.

semanticSearch

Perform vector-based semantic search across article content.

multiSemanticSearch

Batch semantic searches across multiple queries.

createArticle

Create a new article with a title and content.

updateArticle

Update an existing article by filename.

deleteArticle

Delete an article by filename.