mdMCP

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

pip install mdmcp

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.

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 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