nvda-mcp

MCP (Model Context Protocol) server for NVDA screen reader integration. Enables AI agents to control keyboard input and observe speech/braille output for accessibility testing and auditing.

Installation

uv sync

Usage

As MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "nvda": {
      "command": "uv",
      "args": ["run", "nvda-mcp"],
      "cwd": "/path/to/nvda-mcp"
    }
  }
}

Available Tools

Connection:

• connect(host, port?, channel?) - Connect to NVDA Remote server
• disconnect() - Disconnect from server
• ping() - Check connection status

Input:

• send_key(key) - Send a key press (e.g., "Tab", "Enter", "NVDA+T")
• send_keys(keys) - Send a sequence of keys
• send_key_and_wait(key, timeout?) - Send key and wait for resulting speech (recommended)

Output:

• get_speech(since?) - Get recent speech output
• get_braille() - Get current braille display content
• wait_for_speech(timeout?) - Wait for new speech output
• clear_speech_buffer() - Clear the speech buffer

Available Resources

• nvda://speech - Current speech output with timestamps (text/plain)
• nvda://braille - Current braille display content (text/plain)

Resources support MCP subscriptions for real-time updates.

Example Session

> connect localhost
Connected to localhost:6837

> send_key_and_wait Tab
Sent key: Tab
[1734567890.123] Edit, multiline

> send_key_and_wait NVDA+T
Sent key: NVDA+T
[1734567890.456] Notepad

Development

# Install dev dependencies
uv sync

# Run tests
uv run pytest

# Run integration tests (requires NVDA)
uv run pytest --run-integration

# Linting and formatting
uv run ruff check .
uv run ruff format .
uv run ty check src/

Requirements

• Python 3.11+
• NVDA with Remote enabled (built-in since NVDA 2024.1)
• NVDA configured to accept direct connections

License

GNU General Public License v2.0 or later (GPL-2.0-or-later)