Readium MCP

Python Version

Model Context Protocol

License: MIT

PyPI version

A Model Context Protocol (MCP) server that exposes the powerful documentation analysis functionality of Readium for LLMs like Claude and other MCP-compatible clients.

🔍 What is this?

Readium MCP acts as a bridge between LLMs and any documentation repository, allowing:

Analyzing local directories, public/private Git repositories, and URLs
Processing multiple file formats (code, Markdown, text)
Converting web pages to Markdown for analysis
Delivering structured results with summary, file tree, and content

Perfect for when you need an LLM to analyze large bodies of documentation, code repositories, or technical websites.

🚀 Installation

With pip (recommended)

pip install readium-mcp

From source code

# Clone the repository
git clone https://github.com/tu-usuario/readium-mcp.git
cd readium-mcp

# Install dependencies with Poetry
poetry install

🛠️ Usage

Direct execution

readium-mcp

With Poetry (from source code)

poetry run readium-mcp

🔌 Integration with MCP clients

VSCode

Add to your VSCode configuration (settings.json):

{
  "mcp": {
    "servers": {
      "readium": {
        "command": "readium-mcp"
      }
    }
  }
}

Or create a .vscode/mcp.json file in your project:

{
  "servers": {
    "readium": {
      "command": "readium-mcp"
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "readium": {
      "command": "readium-mcp"
    }
  }
}

MCP CLI

# Install
mcp install -n readium -- readium-mcp

# Inspect
mcp inspect readium

# Test in console
mcp call-tool readium analyze_docs --path https://github.com/modelcontextprotocol/servers.git

📝 Exposed tools

analyze_docs

Analyzes documentation from a local directory, Git repository, or URL using Readium.

Parameters

| Parameter | Type | Description | Default | |-----------|------|-------------|---------| | path | string | Local path, GitHub URL, or documentation URL | (required) | | branch | string | Branch to use if it's a repository | null | | target_dir | string | Specific subdirectory to analyze | null | | use_markitdown | boolean | Use Markitdown for conversion | false | | url_mode | string | URL processing mode ('clean', 'full') | "clean" | | max_file_size | integer | Maximum file size in bytes | 5242880 (5MB) | | exclude_dirs | array | Directories to exclude | [] | | exclude_ext | array | Extensions to exclude (e.g., ['.png']) | [] | | include_ext | array | Extensions to include (e.g., ['.md']) | [] |

Response

{
  "content": [
    {"type": "text", "text": "Summary:\n..."},
    {"type": "text", "text": "Tree:\n..."},
    {"type": "text", "text": "Content:\n..."}
  ],
  "isError": false
}

🧪 Testing

Unit tests

poetry run pytest

Direct Readium test

python test.py

🧩 Example usage with Python

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test_readium_mcp():
    server_params = StdioServerParameters(
        command="readium-mcp"
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List tools
            tools = await session.list_tools()
            print(f"Available tools: {tools}")

            # Analyze a repository
            result = await session.call_tool(
                "analyze_docs",
                {"path": "https://github.com/modelcontextprotocol/servers.git"}
            )

            print(f"Analysis result: {result}")

# Run
asyncio.run(test_readium_mcp())

📋 Advantages

Fast: Efficient analysis even for large repositories
Flexible: Works with local directories, Git repositories, and URLs
Configurable: Customize extensions, sizes, and directories to analyze
Compatible: Works with any MCP client (Claude, VSCode, CLI)
Simple: No complex dependencies, stdio transport for maximum compatibility

🤝 Contributing

Contributions are welcome. Please feel free to:

Fork the repository
Create a branch for your feature (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👏 Acknowledgments

Readium for the powerful documentation analysis functionality
Model Context Protocol for the standard LLM communication protocol
FastMCP for the Python SDK for MCP

Developed with ❤️ by Pablo Toledo