Skip to main content
Glama
Jon's Pushover MCP Server

Jon's Pushover MCP Server

by jonmmease
README.md
# Jon's Pushover MCP Server

An MCP server for sending push notifications via [Pushover](https://pushover.net).

## Requirements

- Python 3.10+
- Pushover account with API token and user key

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PUSHOVER_API_TOKEN` | Yes | Application API token from https://pushover.net/apps |
| `PUSHOVER_USER_KEY` | Yes | User key from https://pushover.net |

## Installation

```bash
# Clone the repository
git clone <your-repo-url>
cd jons-mcp-pushover

# Install with uv
uv pip install -e .
```

## Running the Server

```bash
uv run jons-mcp-pushover
```

## Claude Desktop Configuration

Add this to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "pushover": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/jons-mcp-pushover", "jons-mcp-pushover"],
      "env": {
        "PUSHOVER_API_TOKEN": "your-api-token-here",
        "PUSHOVER_USER_KEY": "your-user-key-here"
      }
    }
  }
}
```

## Adding to Claude Code

```bash
# Register the MCP server with Claude Code
claude mcp add jons-mcp-pushover \
  -e PUSHOVER_API_TOKEN=your-api-token-here \
  -e PUSHOVER_USER_KEY=your-user-key-here \
  -- uv run --directory /path/to/jons-mcp-pushover jons-mcp-pushover
```

## Available Tools

### `send_notification`

Send a push notification to your devices.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `message` | string | Yes | - | The notification message body |
| `title` | string | No | App name | Title shown at top of notification |
| `url` | string | No | - | URL to include (tappable in notification) |
| `url_title` | string | No | - | Label for the URL |
| `priority` | integer | No | 0 | Priority: -2 (silent) to 2 (emergency) |
| `sound` | string | No | device default | Notification sound name |

**Example:**
```python
send_notification(
    message="Build completed successfully!",
    title="CI Pipeline",
    url="https://github.com/user/repo/actions",
    url_title="View Build",
    priority=1,
    sound="magic"
)
```

## Development

### Setup

```bash
# Install with dev dependencies
uv pip install -e ".[dev]"
```

### Running Tests

```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src

# Run a specific test
uv run pytest tests/test_pushover.py::test_send_notification_success
```

### Code Quality

```bash
# Type check
uv run mypy src/jons_mcp_pushover

# Format code
uv run black src tests

# Lint code
uv run ruff check src tests
```

## Project Structure

```
jons-mcp-pushover/
├── src/
│   ├── __init__.py
│   └── jons_mcp_pushover/
│       ├── __init__.py          # Package exports
│       ├── constants.py         # Configuration constants
│       ├── exceptions.py        # Custom exceptions
│       ├── utils.py             # Utility functions
│       ├── server.py            # FastMCP server setup
│       └── tools/
│           ├── __init__.py      # Tool exports
│           └── pushover.py      # Pushover notification tool
├── tests/
│   ├── conftest.py              # Test fixtures
│   └── test_pushover.py         # Pushover tool tests
├── pyproject.toml               # Project configuration
├── CLAUDE.md                    # AI assistant guidance
└── README.md                    # This file
```

## Adding New Tools

1. Create a new file in `src/jons_mcp_pushover/tools/` or add to an existing file
2. Write an async function with type hints and a docstring:
   ```python
   async def my_tool(param: str) -> str:
       """Brief description for the MCP tool listing.

       Args:
           param: What this parameter does.

       Returns:
           What the tool returns.
       """
       return f"Result: {param}"
   ```
3. Export from `src/jons_mcp_pushover/tools/__init__.py`
4. Register in `server.py` with `mcp.tool(my_tool)`

## License

MIT

TDQS

A4.1/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of confusion or overlap between tools. The tool 'send_notification' has a clear, singular purpose that is distinct by default.

Naming Consistency5/5

The single tool name 'send_notification' follows a clear verb_noun pattern, and with only one tool, consistency is inherently perfect as there are no other names to compare against.

Tool Count2/5

A single tool is too few for most server purposes, as it limits functionality and suggests a thin or incomplete surface. For a notification service, basic operations like listing or managing notifications might be expected, but only sending is provided.

Completeness2/5

The server's domain appears to be Pushover notifications, but it only offers a send operation. There are significant gaps, such as no ability to retrieve, update, delete, or list notifications, which could cause agent failures in broader workflows.

Maintenance

ActivityInactive
ResponsivenessNo recent community issues