Enables AI assistants to access and read remote markdown documentation via a JSON index file.
Also known as pawcoding/markdown-mcp-resource
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 7, 2026
- License
- MIT
What is markdown-mcp-resource MCP?
markdown-mcp-resource enables AI assistants to access and read remote markdown documentation via a JSON index file.
Summary generated from the project's README
About markdown-mcp-resource MCP server
Providing AI assistants with direct access to remote documentation is the primary function of this server. It allows developers to turn a collection of markdown files hosted on a web server into a structured set of MCP resources. By pointing the server to a remote JSON index file, an AI client can discover, list, and read specific documentation files using a specialized URI pattern.
Users set up the server locally via npx by providing a base URL to an index.json file as a command-line argument. This configuration works with clients like Claude Desktop or OpenCode. The server manages the connection to your documentation site, handling the retrieval of markdown content and using in-memory caching to ensure faster access during a session. It supports complex documentation structures, including nested subdirectories and root-relative paths, making it suitable for large technical manuals.
What you can do with it
- 1Discovering available documentationAsk the AI to list all the documentation files that are currently indexed and available for reading.
- 2Reading specific guidesRequest that the assistant retrieves and displays the full text of a specific installation or configuration guide.
Written from the project's README. Every use case is checked against a quote from it.
How to install markdown-mcp-resource MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall markdown-mcp-resource MCP in Claude Code
$ claude mcp add markdown-mcp-resource -- npx -y markdown-mcp-resourceInstall markdown-mcp-resource MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"markdown-mcp-resource": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Install markdown-mcp-resource MCP in VS Code
.vscode/mcp.json
{
"servers": {
"markdown-mcp-resource": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Install markdown-mcp-resource MCP in VS Code CLI
$ code --add-mcp '{"name":"markdown-mcp-resource","type":"stdio","command":"npx","args":["-y","markdown-mcp-resource"]}'Install markdown-mcp-resource MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"markdown-mcp-resource": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Install markdown-mcp-resource MCP in Codex
$ codex mcp add markdown-mcp-resource -- npx -y markdown-mcp-resourceInstall markdown-mcp-resource MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.markdown-mcp-resource] command = "npx" args = ["-y", "markdown-mcp-resource"]
Install markdown-mcp-resource MCP in Gemini CLI
$ gemini mcp add -s user markdown-mcp-resource npx -- -y markdown-mcp-resourceInstall markdown-mcp-resource MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"markdown-mcp-resource": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablepawcoding/markdown-mcp-resource is public and reachablegithub.com/pawcoding/markdown-mcp-resource ↗Pass
- Package names this repository as its sourcemarkdown-mcp-resource names pawcoding/markdown-mcp-resource as sourcenpmjs.com/package/markdown-mcp-resource ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for markdown-mcp-resourcenpmjs.com/package/markdown-mcp-resource/v/1.2.3#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/pawcoding/markdown-mcp-resource ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from markdown-mcp-resourcePass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmarkdown-mcp-resource
MCP server that makes remote markdown files available as MCP resources.
Overview
This MCP (Model Context Protocol) server enables AI assistants to access and read markdown documentation from remote URLs. It fetches markdown files listed in a remote JSON index file and makes them available as resources that can be queried and retrieved by MCP-compatible clients.
How It Works
The server:
- Takes a base URL to a JSON index file as a command-line argument (e.g.,
https://my-documentation.com/mcp/index.json) - Expects the index file to contain a list of available markdown files and their routes
- Exposes these files as MCP resources with the URI pattern
markdown://{hostname}/{filename} - Caches fetched content in memory to improve performance
- Provides both resource listing, path completion, and direct content retrieval capabilities
Remote Asset Structure
Your documentation site must be structured as follows:
Required: index.json File
Schema Reference:
The expected format for index.json is formally described in the schema.json file in this repository.
The base URL must point to an index.json file that lists all available markdown files and their routes. Routes can be full HTTP(S) URLs or root-relative paths that start with /, for example:
{
"$schema": "https://raw.githubusercontent.com/pawcoding/markdown-mcp-resource/refs/heads/master/schema.json",
"title": "My Documentation",
"description": "Example documentation index",
"files": [
{
"name": "getting-started",
"route": "https://your-site.com/docs/getting-started.md"
},
{
"name": "api-reference",
"route": "https://your-site.com/docs/api-reference.md"
},
{
"name": "tutorials/basic-setup",
"route": "/docs/tutorials/basic-setup.md"
},
{
"name": "tutorials/advanced-config",
"route": "/docs/tutorials/advanced-config.md"
},
{
"name": "troubleshooting",
"route": "/docs/troubleshooting.md"
}
]
}
Markdown Files
Each file listed in the index must be available at the URL specified in the route field. Root-relative routes resolve against the origin of the index file URL, not the path of the index file:
https://your-site.com/docs/
├── index.json # Lists all available files and their routes
├── getting-started.md # Individual markdown files
├── api-reference.md
├── tutorials/
│ ├── basic-setup.md
│ └── advanced-config.md
└── troubleshooting.md
Important Notes:
- File names in the
namefield of the index should NOT include the.mdextension; theroutefield must be a full HTTP(S) URL or root-relative path to the markdown file and include the.mdextension - Root-relative routes must start with
/; path-relative routes such asdocs/getting-started.mdor./docs/getting-started.mdare not supported - Subdirectories are supported (e.g.,
tutorials/basic-setup)
MCP Client Configuration
OpenCode Configuration
Add this to your OpenCode configuration file (replace with the full URL to your index.json):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-documentation": {
"type": "local",
"command": [
"npx",
"-y",
"markdown-mcp-resource@latest",
"https://my-documentation.com/mcp/index.json"
],
"enabled": true
}
}
}
Claude Desktop Configuration
Add this to your Claude Desktop configuration (replace with the full URL to your index.json):
{
"mcpServers": {
"markdown-docs": {
"command": "npx",
"args": [
"-y",
"markdown-mcp-resource@latest",
"https://your-documentation-site.com/docs/index.json"
]
}
}
}
Generic MCP Client
For other MCP clients, use the command (replace with the full URL to your index.json):
npx markdown-mcp-resource@latest https://your-documentation-site.com/docs/index.json
Usage Examples
1. Setting Up Documentation
Create an index.json file on your web server:
{
"$schema": "https://raw.githubusercontent.com/pawcoding/markdown-mcp-resource/refs/heads/master/schema.json",
"files": [
{
"name": "introduction",
"route": "https://yoursite.com/docs/introduction.md"
},
{
"name": "installation",
"route": "https://yoursite.com/docs/installation.md"
},
{
"name": "configuration",
"route": "/docs/configuration.md"
},
{
"name": "api/authentication",
"route": "/docs/api/authentication.md"
},
{
"name": "api/endpoints",
"route": "/docs/api/endpoints.md"
},
{ "name": "examples", "route": "/docs/examples.md" },
{
"name": "troubleshooting",
"route": "/docs/troubleshooting.md"
}
]
}
Ensure corresponding markdown files exist:
https://yoursite.com/docs/introduction.mdhttps://yoursite.com/docs/installation.mdhttps://yoursite.com/docs/api/authentication.md- etc.
2. Querying Available Resources
Once configured, your MCP client can:
- List all available markdown resources
- Retrieve specific markdown content
- Search through available documentation files
3. Example Interaction
User: "What documentation is available?"
Assistant: [Lists all files from index.json]
User: "Show me the installation guide"
Assistant: [Retrieves and displays installation.md content]
Features
- Resource Discovery: Automatically lists available documentation from
index.json - Content Caching: Improves performance by caching fetched markdown files
- Path Completion: Supports auto-completion of file paths
- Error Handling: Graceful handling of missing files or network issues
- Subdirectory Support: Organize documentation in nested folders
Troubleshooting
Common Issues
Error: "Invalid base path"
- Ensure the base URL starts with
http://orhttps://and points to yourindex.json - Example:
https://docs.example.com/index.jsonnotdocs.example.com
No resources found
- Verify
index.jsonexists at the base URL - Check that
index.jsoncontains afilesarray with file names and routes - Ensure file names in the
namefield don't include.mdextension
Failed to fetch file
- Verify the markdown files exist at the expected URLs
- Check for CORS issues if accessing from browser environments
- Ensure proper HTTP headers are set on your web server
Performance Issues
- Consider enabling HTTP caching headers on your web server
- The MCP server caches content in memory during the session
Testing Your Setup
-
Verify your
index.jsonis accessible:curl https://your-site.com/docs/index.json -
Test individual markdown files:
curl https://your-site.com/docs/getting-started.md -
Run the MCP server directly:
npx markdown-mcp-resource@latest https://your-site.com/docs/index.json -
Use the MCP Inspector for interactive testing:
Visit https://modelcontextprotocol.io/legacy/tools/inspector to test your MCP server interactively in a web interface.
Development
Local Development
git clone https://github.com/pawcoding/markdown-mcp-resource.git
cd markdown-mcp-resource
npm install
npm run build
npm start https://your-test-site.com/docs/index.json
Visit https://modelcontextprotocol.io/legacy/tools/inspector to test your MCP server interactively in a web interface.
Building
npm run build
Formatting
npm run format
License
MIT - see LICENSE file for details.
markdown-mcp-resource MCP questions
How do I add markdown-mcp-resource MCP to Claude Code?
Run claude mcp add markdown-mcp-resource -- npx -y markdown-mcp-resource in your terminal. Add --scope user to make it available in every project.
How do I add markdown-mcp-resource MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I configure the server for Claude Desktop?
Add the server to your Claude Desktop configuration using npx and providing the full URL to your index.json file.
What is the required structure for the index file?
The index.json file must contain a 'files' array where each object has a 'name' (without .md) and a 'route' (a full URL or root-relative path).
Does the server support subdirectories?
Yes, the server supports organizing documentation in nested folders and subdirectories.
How does the server handle performance?
The server improves performance by caching fetched markdown content in memory.