Skip to content

K-Dense-AI/scientific-agent-skills / skills/markitdown

markitdown

Verified

Converts heterogeneous documents and selected URIs to Markdown with Microsoft MarkItDown for text analysis, search, and LLM/RAG ingestion. Covers safe local conversion, streams, Office/PDF/data formats, batch workflows, plugins, vision OCR, Azure extraction, and the official MCP server.

references/mcp_and_plugins.md

View on GitHub
# MCP Server and Plugin System

## Official MCP Package

The Microsoft monorepo publishes `markitdown-mcp`. As of October 1, 2026, the package version is `0.0.1a7`; it depends on `markitdown[all]>=0.1.1,<0.2.0` and `mcp>=2.1.1,<3.0.0`. Runtime checks used MCP SDK 2.2.0. The 2.x server API replaces the older FastMCP import.

Pin both packages to ensure the documented converter version:

```bash
uv pip install \
  "markitdown==0.1.8" \
  "markitdown-mcp==0.0.1a7"
```

The server exposes exactly one tool:

```text
convert_to_markdown(uri: str) -> str
```

Accepted URI schemes are `http:`, `https:`, `file:`, and `data:`.

## Transport Modes

### STDIO

STDIO is the default and preferred local transport:

```bash
markitdown-mcp
```

Generic MCP client configuration:

```json
{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp",
      "args": []
    }
  }
}
```

The MCP client launches the server with the same filesystem and network permissions as the client process unless additional sandboxing is applied.

### Streamable HTTP and SSE

```bash
markitdown-mcp --http --host 127.0.0.1 --port 3001
```

Endpoints:

- Streamable HTTP: `http://127.0.0.1:3001/mcp`
- SSE: `http://127.0.0.1:3001/sse`

`--sse` is a deprecated alias for `--http`. Streamable HTTP is stateless and returns JSON responses. The server starts both transports in the same app. Local in-process tests verified tool discovery, conversion, and `/mcp` initialization; no public server was deployed. Expected file/fetch/conversion failures become MCP `ToolError` messages with sensitive internal detail reduced.

## MCP Security Model

The server:

- Has no authentication
- Runs with the current user's privileges
- Can read files accessible to that user through `file:` URIs
- Can fetch network resources accessible to that process
- Accepts broad URI input with no built-in application allowlist

Requirements:

1. Prefer STDIO.
2. Keep HTTP/SSE bound to `127.0.0.1` or `localhost`.
3. Never expose it on `0.0.0.0`, a LAN interface, or the public Internet without a separately designed authenticated gateway and strict input policy.
4. Run it in a container, VM, or sandbox when processing agent-controlled URIs.
5. Mount only the required input directory, preferably read-only.
6. Deny sensitive network ranges and metadata endpoints.
7. Do not give the server access to home-directory secrets, SSH keys, cloud credentials, or broad research storage.

The tested MCP SDK enables Host/Origin checks for localhost transports; these checks are not credentials. Localhost is not authentication: other processes or users on the same machine may still reach the port.

## MCP Plugins

The MCP process disables MarkItDown plugins by default. It enables them only when the named variable is explicitly set to a truthy value:

```bash
MARKITDOWN_ENABLE_PLUGINS=true markitdown-mcp
```

Do this only for installed, reviewed plugins. Enabling plugins loads Python entry points into the server process, expanding both code-execution and file/network capabilities.

## Container Isolation

The official guide recommends Docker for desktop-agent use. A secure deployment should:

- Build from a reviewed, pinned `v0.1.8` source checkout.
- Run as a non-root user.
- Mount a narrow input directory read-only.
- Use a read-only root filesystem when practical.
- Drop unnecessary Linux capabilities.
- Restrict outbound networking.
- Avoid mounting the Docker socket, home directory, or credential stores.

Illustrative runtime shape after building a trusted image (container execution was not tested in this audit):

```bash
docker run --rm -i \
  --read-only \
  --cap-drop ALL \
  -v "/absolute/path/to/documents:/workdir:ro" \
  markitdown-mcp:0.1.8
```

The conversion URI inside the container would use a path under `/workdir`.

## Plugin Discovery

Plugins are Python distributions registered under the `markitdown.plugin` entry-point group.

List discovered plugins without enabling them:

```bash
markitdown --list-plugins
python scripts/inspect_installation.py
```

Enable plugins for one CLI conversion:

```bash
markitdown --use-plugins input.rtf -o output.md
```

Enable in Python:

```python
from markitdown import MarkItDown

converter = MarkItDown(enable_plugins=True)
result = converter.convert_local("input.rtf")
print(result.markdown)
```

## Plugin Trust Checklist

Before installing a plugin:

- Confirm the exact package name; defend against typosquatting.
- Verify the publisher and source repository.
- Review `pyproject.toml`, entry points, dependencies, and install hooks.
- Inspect converters for filesystem, subprocess, environment, and network access.
- Pin an exact version and retain a lockfile/hash in production.
- Test in an isolated environment with non-sensitive documents.
- Re-run review after every update.

Do not install arbitrary packages merely because they use the `#markitdown-plugin` tag.

## Plugin Interface Version 1

### Converter

```python
from typing import Any, BinaryIO

from markitdown import (
    DocumentConverter,
    DocumentConverterResult,
    StreamInfo,
)


class ExampleConverter(DocumentConverter):
    def accepts(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> bool:
        return (stream_info.extension or "").lower() == ".example"

    def convert(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> DocumentConverterResult:
        payload = file_stream.read()
        return DocumentConverterResult(
            markdown=payload.decode("utf-8", errors="replace")
        )
```

`accepts()` must restore the stream position if it reads any bytes.

### Module registration

```python
from markitdown import MarkItDown

__plugin_interface_version__ = 1


def register_converters(markitdown: MarkItDown, **kwargs) -> None:
    markitdown.register_converter(ExampleConverter())
```

### `pyproject.toml`

```toml
[project.entry-points."markitdown.plugin"]
example = "example_markitdown_plugin"
```

MarkItDown calls `register_converters()` when a plugin-enabled instance is constructed and forwards the constructor keywords.

## Converter Priority

Lower values run first:

- Official OCR plugin: `-1.0`
- Specific built-in formats: `0.0`
- Generic text/HTML/ZIP converters: `10.0`

Registering a converter before built-ins can change the parser selected for existing formats. Treat priority as part of the plugin's security and compatibility review.

## Official OCR Plugin

`markitdown-ocr==0.1.1` requires core >=0.1.8 and is an official plugin from the Microsoft monorepo:

```bash
uv pip install \
  "markitdown==0.1.8" \
  "markitdown-ocr==0.1.1" \
  "openai==3.22.1"
```

It sends document images/pages to the configured OpenAI-compatible vision provider. Configuration and disclosure requirements are in `cloud_and_ocr.md`.

## Sources

- MCP guide at v0.1.8: https://github.com/microsoft/markitdown/tree/v0.1.8/packages/markitdown-mcp
- MCP server implementation: https://github.com/microsoft/markitdown/blob/v0.1.8/packages/markitdown-mcp/src/markitdown_mcp/__main__.py
- Sample plugin at v0.1.8: https://github.com/microsoft/markitdown/tree/v0.1.8/packages/markitdown-sample-plugin
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall