MCP server

The TrailHUB MCP server lets an AI assistant read and manage your trail systems in natural language: "Which of my systems have closed trails?", "Close everything at Ridge Park and post a high-wind notice", "Mark Lakeside Loop groomed and track-set."

#What MCP is

The Model Context Protocol (MCP) is an open standard that lets AI applications call external tools. An MCP server is a small program that describes a set of tools (here: "list trails", "post a notice", …) and runs them when the assistant asks. The TrailHUB MCP server is a thin wrapper over the Management API v1: every tool call becomes an API request made with your API key, so it can do exactly what that key allows and nothing more.

#Prerequisites

• Node.js 18 or newer on the computer that runs your MCP client.
• A TrailHUB API key from User Settings → API Keys (see API keys). Name it after the assistant, e.g. "Claude assistant". Use a read-only key if the assistant only needs to answer questions.
• An MCP client: Claude Desktop, Claude Code, Cursor, or any client that supports stdio servers.

The server runs over stdio (no network port) and reads its configuration from environment variables.

#Environment variables

#Setup

#Claude Desktop

1. Open Claude Desktop → Settings → Developer → Edit Config. This opens claude_desktop_config.json.

2. Add a trailhub entry under mcpServers. The simplest form runs the server straight from GitHub with npx:

   Copy

   {
     "mcpServers": {
       "trailhub": {
         "command": "npx",
         "args": ["-y", "github:Orbitist/trail-hub#main:mcp-server"],
         "env": { "TRAILHUB_API_KEY": "th_..." }
       }
     }
   }

   Or, from a local checkout of the trail-hub repository (run npm install inside mcp-server first):

   Copy

   {
     "mcpServers": {
       "trailhub": {
         "command": "node",
         "args": ["/path/to/trail-hub/mcp-server/index.js"],
         "env": { "TRAILHUB_API_KEY": "th_..." }
       }
     }
   }

3. Save and restart Claude Desktop. A tools icon should show trailhub with its tools.

#Claude Code

claude mcp add trailhub -e TRAILHUB_API_KEY=th_... -- node /path/to/trail-hub/mcp-server/index.js

Or with npx:

claude mcp add trailhub -e TRAILHUB_API_KEY=th_... -- npx -y "github:Orbitist/trail-hub#main:mcp-server"

Run claude mcp list to confirm it is registered.

#Other stdio clients (Cursor, etc.)

Any client that launches a stdio MCP server needs three things: the command (node or npx), its arguments (the path to index.js, or the github:… package spec), and the TRAILHUB_API_KEY environment variable. Consult your client's documentation for where to put them; the shape is the same as the Claude Desktop JSON above.

#Tools

Every tool returns the API's JSON response as text. Write tools trigger a recompile, so the public map, stats and embeds update within seconds.

#Account

#Trail systems

#Trails

#Points of interest

#Updates (notices, surface conditions, snow reports)

Enumerations (statuses, difficulties, marker classes, surface conditions) are the same as in the Management API reference.

#Example prompts

Once connected, try:

• "Which of my trail systems have closed trails right now?"
• "List the trails at Chautauqua Rails with their status."
• "Close every trail at Chautauqua Rails and post a danger notice that we're closed for high winds until tomorrow morning. Notify subscribers."
• "Mark Lakeside Loop and Ridge Run as groomed and track-set."
• "Post a snow report: 6 inches in the last 24 hours, base depth 18."
• "Add a parking point at 42.41, -79.31 called 'Lot A'."
• "Set the parking lot wait-time point to Closed."
• "Extend this morning's grooming report so it expires at 6 pm."
• "Reopen everything we closed yesterday."

The assistant will usually call list_trail_systems and list_trails first to resolve names into ids.

#Safety notes

• Everything happens as you. Actions are recorded with your account as the author, exactly as if you had done them in the web app.
• Deletes ask first. delete_trail and delete_point tell the assistant to confirm with you before calling. Deleted trails and points go to the trash and can be restored by a manager in the web app; delete_update is immediate.
• notify: true sends real email and SMS to everyone subscribed to the trail system, the same as ticking "Notify" in the web app. Ask the assistant to show you the wording before it posts with notify, or tell it never to notify.
• Use a read-only key for assistants that only need to read. They can still answer "what's open?" but cannot change anything.
• Restrict the key to one trail system if the assistant should only work on one.
• Revoke the key in User Settings → API Keys if a laptop is lost or a config file is shared by mistake; the server stops working immediately.
• The server has no memory of its own and stores nothing locally; all state lives in TrailHUB.

#Troubleshooting

To see exactly what the key can do, ask the assistant to run whoami, or call GET /api/v1/me yourself with curl.

#Developing the server

The server is a single ES module at mcp-server/index.js in the trail-hub repository.

cd mcp-server
npm install
npm test

createServer() is exported so the same tool set can later be hosted remotely (Streamable HTTP).