shaarli-mcp

MCP connector for a self-hosted Shaarli bookmark manager. It speaks Shaarli REST API v1 over stdio and over stateless Streamable HTTP on localhost.

Shaarli is zlib software. This connector does not copy the PHP application. It is not affiliated with the Shaarli project.

shaarli.routes.json lists every $this->get|post|put|delete call in the /api/v1 group of index.php (v0.16.10). All 11 routes are tool actions. None are excluded. scripts/gen-operations.mjs writes src/operations.ts from that file. Do not edit src/operations.ts by hand.

SHAARLI_URL and SHAARLI_API_SECRET are required. There is no default origin. Each request mints a JWT with header {"typ":"JWT","alg":"HS512"}, payload {"iat": <unix seconds>}, and HMAC-SHA512 of header.payload using the instance API secret. The client sends Authorization: Bearer <jwt>. Shaarli rejects iat in the future and iat older than 540 seconds (ApiMiddleware::$TOKEN_DURATION).

Setup

npm install
npm run ci
npm start
npm run start:http

npm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication of its own. Keep it on localhost.

{
  "mcpServers": {
    "shaarli": {
      "command": "node",
      "args": ["/workspace/connectors/shaarli/dist/index.js"],
      "env": {
        "SHAARLI_URL": "http://127.0.0.1:8097",
        "SHAARLI_API_SECRET": "...",
        "SHAARLI_ALLOW_WRITES": "false"
      }
    }
  }
}

The API secret is the value from Shaarli administration, not a session cookie. The connector never prints it.

Docker, HTTP, no authentication, keep it on localhost.

docker build -t shaarli-mcp .
docker run -p 127.0.0.1:3000:3000 \
  -e SHAARLI_URL=http://127.0.0.1:8097 \
  -e SHAARLI_API_SECRET=... \
  shaarli-mcp

Do not put secrets in the image.

Regenerate the registry after a route bump.

npm run gen:operations

scripts/live-check.mjs talks to a real server over stdio. It reads the secret from SHAARLI_API_SECRET or from SHAARLI_API_SECRET_FILE (default /workspace/tools/shaarli/api.secret). It unsets DATABASE_URL. It prints pass or fail lines only, and it redacts the secret and JWTs. It does not run inside npm run ci.

Related MCP server: mcp-shlink

Config

Invalid values are reported by field name and issue code. The rejected value is not included.

Calls go to /api/v1 plus the PHP path. Accept is application/json. JSON writes send Content-Type: application/json.

Safety

Reads run without a write flag. A write still needs confirm set to the boolean true and SHAARLI_ALLOW_WRITES=true. The string "true" is rejected. Otherwise the tool returns a dry-run preview of method, path, query, and body, and it sends nothing. Omit confirm and blocked is false. Confirm true with writes disabled and blocked is true.

PUT /api/v1/links/{id} replaces title, url, description, tags, and private. The update action fetches the current link, merges the fields you pass, and PUTs the merged object. The preview body is that merged object.

HTTP 401 is unauthorized. HTTP 400 and 422 are invalid input. HTTP 404 is not found. HTTP 409 is conflict (duplicate URL). HTTP 429 includes Retry-After when the header is present. Other failures are server, network, or timeout. Response bodies are capped at 1,000,000 bytes.

The API secret and any JWT are redacted in logs, errors, and tool results.

Tools

Three tools. Each takes action plus the fields for that action.

shaarli_links search is GET /api/v1/links with searchterm, searchtags, visibility (all, public, private), offset, and limit (a number, or all). Default limit on Shaarli is 20. get needs id.

create accepts url, title, description, tags, and private. An empty URL creates a note. A duplicate URL is HTTP 409.

update needs id and at least one of url, title, description, tags, private.

Shaarli tag path names match [\w]+. Hyphens and spaces do not match the route.

history accepts since (ISO 8601), offset, and a numeric limit. Shaarli rejects limit=all on history.

Other MCP servers

gh search repos "shaarli mcp" returned no Shaarli MCP repository. npm search for shaarli mcp did not return a Shaarli connector. There is no published Shaarli MCP tool list to compare against. The official python-shaarli-client is a CLI, not MCP.

If you run Linkding instead of Shaarli, use the sibling linkding-mcp connector.

Live check

See LIVE-CHECK.md. Run unset DATABASE_URL then npm run live-check against a Shaarli origin. The script never prints the API secret.

License

MIT. Shaarli itself is zlib. This connector only talks to the published REST API.