mdMCP

Turn a Markdown file into a local MCP server, with zero dependencies.

pip install markdown-mcp-server

Quickstart

1. Write a tool file:

## Tool: health_check
Check if a URL is reachable.
### Parameters
- url (string, required): URL to check
### Execute
\```bash
STATUS=$(curl -sf -o /dev/null -w '%{http_code}' -m 5 "$MDMCP_URL")
echo "HTTP $STATUS"
\```

2. Serve it:

mdmcp serve tools.md

3. Connect to Claude Code:

{
  "mcpServers": {
    "my-tools": {
      "command": "mdmcp",
      "args": ["serve", "tools.md"]
    }
  }
}

That's it. Your Markdown is now an MCP server.

Related MCP server: mcp-markdown-tools

How it works

• ## Tool: name defines a tool

• ### Parameters defines input schema (envvar-based, no string interpolation)

• ### Execute contains a bash script inside a fenced code block

• Parameters are passed as $MDMCP_<NAME> environment variables

Commands

mdmcp list tools.md              # List available tools
mdmcp validate tools.md          # Validate tool definitions
mdmcp run tools.md tool_name '{}'  # Run a tool once
mdmcp serve tools.md             # Start MCP stdio server

Security

• Minimal env: only PATH, HOME, USER, SHELL, LANG, TERM are inherited. API keys and tokens are NOT exposed to tool scripts.

• No string interpolation: parameters are passed as environment variables, not injected into shell code.

• Required param validation: missing required parameters return an error before execution.

• Timeout + process cleanup: 30s timeout with process group kill to prevent zombies.

Tips

• Always quote "$MDMCP_VAR" in bash to prevent word splitting

• Use ${MDMCP_VAR:-default} for optional params with bash-side defaults

• You can use python3 -c inside bash for complex logic (see examples/data-tools.md)

• Use set -eu at the top of scripts for safer execution

Examples

See the examples/ directory:

• ops-tools.md — disk usage, port check, git log, docker status, health check

• dev-tools.md — find TODOs, run linter, check port (from Codex dogfood)

• data-tools.md — CSV summary, JSON inspect, file diff (from Gemini dogfood)

Known limitations

• Execute blocks only support ``` fences (not ~~~)

• Parameter names must be \w+ (no spaces or special chars)

• Nested ``` inside heredocs will confuse the parser

• All parameter values are strings in bash; cast manually if needed

License

MIT