Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@markdown-new-mcp Convert this PDF to markdown: https://example.com/report.pdf"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP (Model Context Protocol) server for markdown.new file conversion API. Convert PDF, DOCX, XLSX, images and 20+ formats to Markdown.
npm install markdown-new-mcpRelated MCP server: MarkItDown MCP
For stdio MCP clients, use npx -y so the server starts under Node.js and preserves the JSON-RPC stdio stream. Add this to your Claude config:
{
"mcpServers": {
"markdown-new": {
"command": "npx",
"args": ["-y", "markdown-new-mcp@latest"]
}
}
}Add this to the mcp section of ~/.config/opencode/opencode.json:
{
"mcp": {
"markdown-new": {
"type": "local",
"command": ["npx", "-y", "markdown-new-mcp@latest"]
}
}
}For higher rate limits, you can provide an API key via environment variable:
{
"mcpServers": {
"markdown-new": {
"command": "npx",
"args": ["-y", "markdown-new-mcp@latest"],
"env": {
"MARKDOWN_NEW_API_KEY": "mk_your_api_key_here"
}
}
}
}Optional:
MARKDOWN_NEW_TIMEOUT_MS: request timeout in milliseconds for upstream API calls (default: 30000)
convert_url_to_markdownConvert a remote file URL to clean Markdown text. Supports PDF, DOCX, XLSX, images, and 20+ formats.
Parameters:
url (string, required): HTTP or HTTPS URL of the remote file
api_key (string, optional): API key for higher rate limits; the server also reads MARKDOWN_NEW_API_KEY
Example:
Convert this PDF to markdown: https://example.com/document.pdfconvert_file_to_markdownConvert a local file to clean Markdown text. The path must be absolute and visible to the server process. Supports PDF, DOCX, XLSX, images, and 20+ formats.
Parameters:
file_path (string, required): The absolute path to the local file
api_key (string, optional): API key for higher rate limits; the server also reads MARKDOWN_NEW_API_KEY
Example:
Convert /path/to/document.pdf to markdownconvert_url_to_jsonConvert a remote file URL to structured JSON, including metadata such as title, tokens, and duration. Supports PDF, DOCX, XLSX, images, and 20+ formats.
Parameters:
url (string, required): The URL of the remote file
api_key (string, optional): API key for higher rate limits; the server also reads MARKDOWN_NEW_API_KEY
Documents: PDF, DOCX, ODT
Spreadsheets: XLSX, XLS, XLSM, XLSB, ET, ODS, Numbers
Images: JPG, JPEG, PNG, WebP, SVG
Text/Data: TXT, MD, CSV, JSON, XML, HTML, HTM
Without API Key: 500 requests/day per IP
With API Key: Higher limits available
Maximum File Size: 10MB
# Install dependencies
npm install
# Build
npm run build
# Run locally
npm run dev
# Smoke test the stdio MCP server
npm run build
npm run smoke:stdio -- node dist/index.jsMIT
Convert a local file to clean Markdown text. The path must be absolute and visible to the server process. Supports PDF, DOCX, XLSX, images, and 20+ formats.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | Optional markdown.new API key. Leave empty to use MARKDOWN_NEW_API_KEY from the server environment. | |
| file_path | Yes | Absolute path to a local file visible to this MCP server process. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description usefully adds the constraint that the path must be absolute and visible to the server process, but it never discloses that conversion apparently runs through the markdown.new external API (per the api_key parameter), which is the key behavioral fact implied by openWorldHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the core purpose and the two most important constraints front-loaded; every clause carries information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does convey the return form ('clean Markdown text') and the supported formats, which is most of what an agent needs. It stops short of noting the external-service dependency or any failure modes for unsupported/oversized files.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema. The description's format list (PDF, DOCX, XLSX, images, 20+ formats) is input-relevant context but not parameter-level semantics, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (convert) and resource (local file) plus the output form (clean Markdown text). The word 'local' plus the name clearly distinguishes it from the sibling convert_url_to_markdown and convert_url_to_json tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the 'local file' framing versus the URL-based siblings, but the description never explicitly says when to choose this over convert_url_to_markdown or convert_url_to_json. No prerequisites or exclusions beyond the absolute-path note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a remote file URL to structured JSON, including metadata such as title, tokens, and duration. Supports PDF, DOCX, XLSX, images, and 20+ formats.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | HTTP or HTTPS URL of the remote file to convert into a structured JSON response. | |
| api_key | No | Optional markdown.new API key. Leave empty to use MARKDOWN_NEW_API_KEY from the server environment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile of a network read is covered. The description adds genuine context by listing supported formats (PDF, DOCX, XLSX, images, 20+), but it omits handling of failures (bad URL, unsupported format, large file) or rate/size limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the operation and its output shape lead, with the format-support detail following. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so partially by naming title, tokens, and duration as included fields. A read-only, two-parameter tool needs little more; only error behavior and limits are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% – both url and api_key are fully documented inline, including the environment-variable fallback. The description adds nothing beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (convert a remote file URL to structured JSON) and enumerates supported input formats, so the agent knows exactly what operation this is. It does not, however, distinguish itself from the siblings convert_url_to_markdown and convert_file_to_markdown, which share nearly identical framing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance or reference to the sibling tools. The agent must infer from the output noun ('JSON') that this is the structured-data variant rather than the markdown variant, which is a reasonable but unstated inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a remote file URL to clean Markdown text. Supports PDF, DOCX, XLSX, images, and 20+ formats.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | HTTP or HTTPS URL of the remote file to convert into Markdown. | |
| api_key | No | Optional markdown.new API key. Leave empty to use MARKDOWN_NEW_API_KEY from the server environment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and network access. The description adds supported file formats (PDF, DOCX, XLSX, images, 20+), which is useful context beyond annotations, but says nothing about output characteristics, size limits, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no wasted words. The core action and format support are both front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, read-only conversion tool with full schema coverage and annotations, the description covers purpose and format support adequately. It could be more complete by hinting at output size or distinguishing itself from siblings, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (url, api_key) are fully documented in the schema. The description adds no parameter-level detail beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (convert) and resource (remote file URL to Markdown), and lists supported formats. However, it does not explicitly differentiate itself from the sibling convert_file_to_markdown, forcing the agent to infer that 'remote URL' means this tool versus a local file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The mention of 'remote file URL' implies usage for URL-based conversion, but there is no explicit guidance on when to choose this over convert_file_to_markdown or convert_url_to_json, nor any exclusions or prerequisites stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.4convert_file_to_markdownconvert_url_to_jsonconvert_url_to_markdownScored across 3 tools
Each tool targets a distinct combination of input source (URL vs local file) and output format (Markdown vs JSON), and the descriptions clearly state these differences, leaving no ambiguity in selection.
All three tools follow the identical pattern convert_{source}_to_{format}, using snake_case consistently and predictable verb-noun structure throughout.
Three tools is well-scoped for a focused file-conversion server, covering the primary source-output combinations without unnecessary bloat or glaring thinness.
The surface covers URL→Markdown, file→Markdown, and URL→JSON, but omits file→JSON conversion, which is an obvious companion operation given the existing URL→JSON tool. This gap may force workarounds for local files needing structured output.
Convert documents and web pages to clean Markdown: PDF, DOCX, XLSX, EPUB, scanned files, any URL.
Convert PDF, DOCX, HTML, and URLs to clean, LLM-ready markdown with tables preserved
Parse PDF/Word/PPT/HTML to Markdown; tables as JSON, image extraction, RAG chunking, page ranges.
Convert files, URLs, and documents to clean, AI-ready Markdown via MCP.
