Readables MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to save content directly to your readables.ai library.

Features

• QR Code Authentication: Secure authentication using your readables.ai mobile app
• Content Saving: Save text, markdown, HTML, and JSON content to your readables.ai library
• Automatic Processing: Content is automatically processed and made searchable in your library
• Zero Configuration: Works out of the box with any MCP-compatible AI assistant

Installation

Using npx (Recommended)

No installation required! Just add the server to your AI assistant's MCP configuration:

{
  "mcpServers": {
    "readables": {
      "command": "npx",
      "args": ["@readables/mcp-server"]
    }
  }
}

Global Installation

npm install -g @readables/mcp-server

Then configure your AI assistant:

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

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "readables": {
      "command": "npx",
      "args": ["@readables/mcp-server"]
    }
  }
}

Environment Variables

• READABLES_API_KEY: Optional. Pre-configured API key (skips QR authentication)

Authentication

First Time Setup

1. Start your AI assistant with the MCP server configured
2. Say: "authenticate readables" to begin authentication
3. The assistant will display a QR code image and session ID
4. Open the readables.ai mobile app and scan the QR code
5. Use the complete_readables_auth tool with the provided session ID
6. You can now save content to readables.ai!

Using Pre-configured API Key

If you have an API key from readables.ai:

export READABLES_API_KEY="your-api-key-here"

Or add it to your shell profile for persistence.

Usage

Once configured, you can use readables.ai:

Authentication

• "authenticate readables" - Start the authentication process

Saving Content

• "Save this conversation to readables"
• "Send this code to readables"
• "Store this article in my readables library"
• "Save this research to readables"

The server will automatically:

1. Check if you're authenticated (if not, prompt you to authenticate)
2. Save the content to your readables.ai account
3. Trigger processing for text extraction and analysis
4. Make the content searchable in your library

Supported Content Types

• Plain Text (text/plain)
• Markdown (text/markdown)
• HTML (text/html)
• JSON (application/json)

API

Tools

authenticate_readables

Starts the authentication process with readables.ai. Use this when prompted to "authenticate readables".

Parameters: None

Example:

await callTool('authenticate_readables', {});

save_to_readables

Saves content to your readables.ai library. If not authenticated, prompts you to authenticate first.

Parameters:

• content (required): The content to save
• title (optional): Title for the content
• contentType (optional): Content type (defaults to text/plain)

Example:

await callTool('save_to_readables', {
  content: 'This is my important note',
  title: 'Important Note',
  contentType: 'text/markdown'
});

complete_readables_auth

Completes the authentication process after scanning the QR code with the readables.ai mobile app.

Parameters:

• sessionId (required): The session ID provided when the QR code was displayed

Example:

await callTool('complete_readables_auth', {
  sessionId: 'uuid-session-id-from-qr-response'
});

Troubleshooting

QR Code Issues

• QR code too large or not displaying properly: This was completely fixed in version 1.0.5. QR codes are now displayed as properly sized images. Update to the latest version:

  npx @readables/mcp-server@latest

• Error: "qrcode.generate is not a function": This was fixed in version 1.0.1+. Make sure you're using the latest version.

• MCP Protocol Errors / JSON parsing issues: This was completely fixed in version 1.0.3+. The authentication now works through proper MCP tool responses.

Authentication Issues

• QR code not displaying: Make sure you're using version 1.0.5+ where QR codes are shown as images in the assistant's response
• QR code not scannable: The new image-based QR codes (v1.0.5+) are properly sized and easily scannable
• Authentication not completing: Use the complete_readables_auth tool with the session ID after scanning the QR code

Authentication Issues

• Ensure you have the readables.ai mobile app installed
• Check that your device has internet connectivity
• Try regenerating the QR code by restarting the authentication flow

Connection Issues

• Verify the API URL is correct
• Check your internet connection
• Ensure your API key hasn't expired

Permission Issues

• Make sure you have permission to install npm packages globally (if using global install)
• Try using npx instead of global installation

Development

Building from Source

git clone <repository-url>
cd mcp-server
npm install
npm run build
npm start

Publishing to npm

1. Build the package:

   cd mcp-server
   npm install
   npm run build

2. Test the build:

   node dist/index.js --help

   Run the build locally in MCP inspector:

   npx @modelcontextprotocol/inspector node dist/index.js

3. Publish to npm:

   For scoped packages (recommended):

   npm publish --access public

License

MIT

Support

For support, please visit readables.ai or contact [email protected].