Meridian 59 API (`m59api`)

A companion tool for Meridian 59 servers providing two optional features:

HTTP API - Query and control your M59 server via the maintenance port
Discord Webhooks - Real-time game event notifications

Each feature requires configuration in your M59 server's blakserv.cfg. Use one or both.

Quick Start

1. Configure your M59 server

Edit blakserv.cfg to enable the features you want:

For HTTP API (maintenance port access):

[Socket]
MaintenancePort      9998
MaintenanceMask      127.0.0.1

For Discord Webhooks (game event notifications):

[Webhook]
Enabled              Yes

Note: Webhook support requires PR #1176 or later. If your server fork predates this, see that PR for the implementation.

2. Install m59api

pip install m59api

Windows + Webhooks: Also install pywin32 for named pipe support:

pip install pywin32

3. Set Discord webhook URL (if using webhooks)

# Windows PowerShell:
$env:DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"

# Linux/macOS:
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"

4. Start services (order matters!)

# Start m59api FIRST
m59api

# Then start your M59 server
./blakserv

Important: m59api must be running before the M59 server starts. The server connects to pipes created by m59api. If you start the server first, webhooks will silently fail.

5. Use the features you configured

HTTP API: Open http://127.0.0.1:8000/docs
Webhooks: Game events will appear in your Discord channel

Installation

pip install m59api

Official PyPI page: https://pypi.org/project/m59api/

Command Line Options

m59api [OPTIONS]

Option	Default	Description
`--host`	`127.0.0.1`	Host to bind to
`--port`	`8000`	Port to bind to
`--reload`	off	Enable auto-reload for development
`--log-level`	`info`	Log level (debug, info, warning, error)
`--config`	(auto-detect)	Path to m59api.json config file

Examples:

# Default settings
m59api

# Custom host/port with debug logging
m59api --host 0.0.0.0 --port 8000 --log-level debug

# With explicit config file
m59api --config /path/to/m59api.json

Real-time Webhook Integration

m59api listens for messages from your Meridian 59 server via cross-platform pipes:

Windows: Named pipes \\.\pipe\m59apiwebhook1 through \\.\pipe\m59apiwebhook10
Linux/macOS: FIFO pipes /tmp/m59apiwebhook1 through /tmp/m59apiwebhook10

When your M59 server sends events, they appear in Discord as formatted messages with timestamps and emojis.

Multi-Server Webhook Routing

For running multiple M59 servers on the same machine, each routing to different Discord channels.

How It Works

Each M59 server can be configured with a prefix in its blakserv.cfg. The prefix determines which pipes the server writes to, and m59api routes messages from each prefix to a different Discord webhook.

flowchart LR
    subgraph "M59 Servers"
        S1["Server 1<br/>(blakserv.cfg)<br/>Prefix: 101"]
        S2["Server 2<br/>(blakserv.cfg)<br/>Prefix: 102"]
        S3["Dev Server<br/>(blakserv.cfg)<br/>Prefix: dev"]
    end

    subgraph "Named Pipes"
        P1["101_m59apiwebhook1-10"]
        P2["102_m59apiwebhook1-10"]
        P3["dev_m59apiwebhook1-10"]
    end

    subgraph "m59api"
        C["Config Loader<br/>(m59api.json)"]
        L1["Pipe Listeners<br/>prefix: 101"]
        L2["Pipe Listeners<br/>prefix: 102"]
        L3["Pipe Listeners<br/>prefix: dev"]
        R["Webhook Router"]
    end

    subgraph "Discord"
        D1["#server-101-events"]
        D2["#server-102-events"]
        D3["#dev-testing"]
    end

    S1 -->|writes| P1
    S2 -->|writes| P2
    S3 -->|writes| P3

    C --> L1
    C --> L2
    C --> L3

    P1 --> L1
    P2 --> L2
    P3 --> L3

    L1 --> R
    L2 --> R
    L3 --> R

    R -->|webhook_url for 101| D1
    R -->|webhook_url for 102| D2
    R -->|webhook_url for dev| D3

Configuration

Create m59api.json in one of these locations (searched in order):

Path specified by --config CLI argument
Path in M59API_CONFIG environment variable
./m59api.json (current directory)
~/.m59api.json (home directory)
/etc/m59api.json (Linux/macOS only)

Example m59api.json:

{
  "default_webhook_url": "https://discord.com/api/webhooks/.../fallback",
  "servers": [
    {
      "prefix": "",
      "webhook_url": "https://discord.com/api/webhooks/.../main-server"
    },
    {
      "prefix": "101",
      "webhook_url": "https://discord.com/api/webhooks/.../server-101"
    },
    {
      "prefix": "102",
      "webhook_url": "https://discord.com/api/webhooks/.../server-102"
    },
    {
      "prefix": "dev",
      "webhook_url": "https://discord.com/api/webhooks/.../dev-testing"
    }
  ]
}

M59 Server Configuration

In each server's blakserv.cfg:

# Server 1
[Webhook]
Enabled              Yes
Prefix               101

# Server 2
[Webhook]
Enabled              Yes
Prefix               102

# Dev server
[Webhook]
Enabled              Yes
Prefix               dev

Pipe Naming

Server Prefix	Pipes Created (10 per server)
(empty)	`m59apiwebhook1` - `m59apiwebhook10`
`101`	`101_m59apiwebhook1` - `101_m59apiwebhook10`
`102`	`102_m59apiwebhook1` - `102_m59apiwebhook10`
`dev`	`dev_m59apiwebhook1` - `dev_m59apiwebhook10`

Backwards Compatibility

If no m59api.json is found, m59api falls back to the DISCORD_WEBHOOK_URL environment variable and creates the default (no-prefix) pipes. Existing single-server setups continue to work without changes.

Validation

Invalid webhook URLs (not starting with https://) log a warning but don't fail startup
Missing webhook_url for a server entry causes that entry to be skipped
No hot-reload: restart m59api after config changes

Troubleshooting

Config file not loading

Check which config file m59api is using:

m59api --log-level debug

Use an explicit path:

m59api --config /full/path/to/m59api.json

Webhooks not appearing in Discord

Check startup order:

# WRONG - server starts first, pipes don't exist yet
./blakserv &
m59api

# RIGHT - m59api creates pipes first
m59api &
sleep 2
./blakserv

Verify pipes exist:

# Windows PowerShell
Get-ChildItem \\.\pipe\ | Select-String "m59api"

# Linux/macOS
ls -la /tmp/*m59apiwebhook*

Test webhook URL manually:

curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"content":"Test message"}'

Messages going to wrong Discord channel

Check which webhook URL is routing to the pipe:

m59api --log-level debug
# Look for lines like: "Routing messages from 101_m59apiwebhook1 to https://..."

Verify prefix in your M59 server's blakserv.cfg:

[Webhook]
Prefix               101  # Must match config file

m59api not receiving messages

Check M59 server webhook is enabled:

# In blakserv.cfg
[Webhook]
Enabled              Yes

Check pipe permissions (Linux/macOS):

ls -la /tmp/*m59apiwebhook*
# Should show: prw-rw-rw- (pipes)

Test pipe manually:

# Linux/macOS
echo '{"message":"Test from pipe"}' > /tmp/m59apiwebhook1

# Windows PowerShell
"Test" | Out-File -FilePath \\.\pipe\m59apiwebhook1 -Encoding ASCII

HTTP API not responding

Check maintenance port config:

# In blakserv.cfg
[Socket]
MaintenancePort      9998
MaintenanceMask      127.0.0.1

Test maintenance port:

# Should connect successfully
telnet 127.0.0.1 9998

Check m59api is running:

# Windows
tasklist | findstr m59api

# Linux/macOS
ps aux | grep m59api

Security

m59api exposes an HTTP API with admin endpoints (account creation, server commands). Follow these guidelines for production deployments:

Bind to localhost only (recommended)

m59api --host 127.0.0.1

This is the default. Webhooks still work (outbound to Discord), but the HTTP API is only accessible locally.

Do NOT expose to the internet

Using --host 0.0.0.0 exposes all admin endpoints to anyone who can reach the port. The blakserv MaintenanceMask setting does NOT protect against m59api relaying commands.

Remote access via SSH tunnel

If you need remote access to Swagger UI:

# From your local machine
ssh -L 8000:localhost:8000 user@your-server

Then open http://localhost:8000/docs in your browser.

Firewall rules

If you must expose the API, use firewall rules (AWS Security Groups, iptables) to restrict access to specific IPs.

API Documentation

Swagger UI: http://127.0.0.1:8000/docs
ReDoc UI: http://127.0.0.1:8000/redoc

How It Works

HTTP API: Connects to Meridian 59 maintenance port to query/control server state
Real-time Integration: Listens for push messages via OS pipes for instant Discord notifications
Cross-platform: Works on Windows (named pipes), Linux and macOS (FIFO pipes)
Multi-server: Routes messages from different server prefixes to different Discord webhooks

Disclaimer

This project is an independent, community-created tool for managing Meridian 59 servers.
It is not affiliated with, endorsed by, or supported by the official Meridian 59 project or its trademark holders.

Use at your own risk.
No warranty is provided. The authors are not responsible for any issues, data loss, or damages resulting from the use of this software.

Meridian 59 is a registered trademark of Andrew and Christopher Kirmse.
The official Meridian 59 repository can be found at:
https://github.com/Meridian59/Meridian59

Name		Name	Last commit message	Last commit date
Latest commit History 56 Commits
.github/workflows		.github/workflows
docs/internal		docs/internal
m59api		m59api
.gitignore		.gitignore
MANIFEST.in		MANIFEST.in
README.md		README.md
m59api.example.json		m59api.example.json
m59api_docker_m59.code-workspace		m59api_docker_m59.code-workspace
requirements.txt		requirements.txt
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

Meridian 59 API (m59api)

Quick Start

1. Configure your M59 server

2. Install m59api

3. Set Discord webhook URL (if using webhooks)

4. Start services (order matters!)

5. Use the features you configured

Installation

Command Line Options

Real-time Webhook Integration

Multi-Server Webhook Routing

How It Works

Configuration

M59 Server Configuration

Pipe Naming

Backwards Compatibility

Validation

Troubleshooting

Config file not loading

Webhooks not appearing in Discord

Messages going to wrong Discord channel

m59api not receiving messages

HTTP API not responding

Security

Bind to localhost only (recommended)

Do NOT expose to the internet

Remote access via SSH tunnel

Firewall rules

API Documentation

How It Works

Disclaimer

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Meridian 59 API (`m59api`)

Packages