NORA Data MCP Server

Read-only MCP server that exposes NORA Dashboard data from Upstash Redis.

Prerequisites

• Python 3.10+ (the mcp package requires it)

• uv (recommended) or pip

Setup

1. Copy .env.example to .env and fill in the Upstash Redis credentials:

   cp .env.example .env

2. Install dependencies:

   # With uv (recommended — handles Python version automatically):
   uv sync
   
   # Or with pip:
   pip install -e .

Running Locally (stdio transport)

# With uv:
uv run python server.py

# Or directly:
python server.py

Claude Desktop Configuration

Add to your Claude Desktop MCP config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "nora-data": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/ahale/nora-mcp-server", "python", "server.py"],
      "env": {
        "KV_REST_API_URL": "https://your-redis-instance.upstash.io",
        "KV_REST_API_READ_ONLY_TOKEN": "your-read-only-token"
      }
    }
  }
}

Claude Code Configuration

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "nora-data": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/ahale/nora-mcp-server", "python", "server.py"],
      "env": {
        "KV_REST_API_URL": "https://your-redis-instance.upstash.io",
        "KV_REST_API_READ_ONLY_TOKEN": "your-read-only-token"
      }
    }
  }
}

Remote Deployment (Hosted Mode)

The server supports streamable-http transport for remote access. When deployed, team members can connect to it without running anything locally.

Deploy to Railway

1. Push this repo to GitHub

2. Create a new project on Railway

3. Connect the GitHub repo

4. Add environment variables in Railway dashboard:

   • KV_REST_API_URL — your Upstash Redis URL

   • KV_REST_API_READ_ONLY_TOKEN — your read-only token

   • MCP_TRANSPORT — streamable-http (set automatically via Dockerfile)

   • PORT — Railway sets this automatically

5. Deploy — Railway will build from the Dockerfile

Docker Build & Run

docker build -t nora-mcp-server .
docker run -p 8000:8000 \
  -e KV_REST_API_URL="https://your-redis-instance.upstash.io" \
  -e KV_REST_API_READ_ONLY_TOKEN="your-read-only-token" \
  nora-mcp-server

Connecting via Cowork / Claude Code (Remote)

Once deployed, team members add the remote MCP server in their project settings:

{
  "mcpServers": {
    "nora-data": {
      "type": "url",
      "url": "https://your-deployed-url.up.railway.app/mcp/"
    }
  }
}

The streamable-http transport serves the MCP endpoint at /mcp/ by default.

Security Note

The server is read-only (it only reads from Upstash Redis with a read-only token). Authentication is not currently implemented — access control relies on URL obscurity and hosting platform network settings. Add bearer token auth if the server is exposed to the public internet.

Available Tools

Architecture

• Transport: stdio (local) or streamable-http (hosted)

• Data source: Upstash Redis REST API (read-only token)

• Redis key pattern: prod:table:{name}.json

• Caching: Per-request cache (tables fetched once per tool call, not persisted)

• Error handling: All tools return JSON; errors are returned as {"error": "..."}, never thrown