fing-mcp-server

MCP server for the Fing local API. It exposes Fing network devices and presence data to MCP clients over HTTP using both Streamable HTTP and SSE.

This server is designed to run on PC-FEDERICO, where Fing Agent exposes the local API on http://localhost:49090 and stores its auth token in:

%APPDATA%\FingAgent\conf\localapi\fingagent.json

How It Works on my machine

At startup the server:

1. Reads the Fing local API config from %APPDATA%\FingAgent\conf\localapi\fingagent.json
2. Extracts the real port and auth values
3. Calls the local API endpoints directly:
   • /devices?auth=...
   • /people?auth=...

On Windows it uses curl.exe as the local transport because Fing Agent returns HTTP responses that are accepted by curl.exe but can break Node's native HTTP client parsing.

Requirements

• Node.js 18+
• Fing Desktop or Fing Agent running on the same machine
• Fing local API enabled

Setup

npm install
npm run build
npm start

If the server is launched on PC-FEDERICO, no manual API key setup is required as long as Fing Agent is already configured and the local API file exists.

Environment Variables

Variable	Default	Description
FING_LOCALAPI_AUTH	auto-discovered	Explicit Fing local API auth token
FING_API_KEY	alias of FING_LOCALAPI_AUTH	Backward-compatible auth token env var
FING_LOCALAPI_PORT	auto-discovered or 49090	Override the local API port
FING_BASE_URL	auto-discovered or http://localhost:49090	Override the Fing local API base URL
FING_LOCALAPI_CONFIG	%APPDATA%\FingAgent\conf\localapi\fingagent.json	Override the Fing local API config file path
PORT	3010	Port used by this MCP server

Notes:

• The old /1 suffix is not used by Fing Agent local API on PC-FEDERICO.
• If both env vars and local config are present, env vars win.

Run in Development

npm run dev

Endpoints

• GET /mcp SSE endpoint for mcp-remote
• POST /mcp/message SSE message endpoint for mcp-remote
• POST /mcp Native Streamable HTTP MCP endpoint
• GET /health Health check

MCP Tools

fing_get_devices

Returns devices discovered by Fing Agent.

Arguments:

• filter_state: UP | DOWN | ALL
• response_format: text | json

fing_get_people

Returns presence information for people configured in Fing.

Arguments:

• filter_state: ONLINE | OFFLINE | ALL
• response_format: text | json

Claude Desktop / mcp-remote

Example claude_desktop_config.json entry:

{
  "mcpServers": {
    "fing": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "http://PC-FEDERICO:3010/mcp"
      ]
    }
  }
}

If you expose the server over Tailscale or another remote network, replace the host with the reachable IP or DNS name of PC-FEDERICO.

Troubleshooting

• Unauthorized: invalid Fing local API auth token The local API auth token is wrong or outdated.
• Fing agent service is unavailable Fing Desktop or Fing Agent is not running.
• curl.exe is required on Windows The server is running on Windows without the built-in curl executable available in PATH.

License

MIT. See LICENSE.