mikrotik-mcp

A Model Context Protocol server that runs RouterOS commands on MikroTik routers over SSH.

Node + TypeScript, no runtime toolchain of its own, and stateless: every tool call re-reads the config and opens and closes its own SSH connection. Nothing is cached, pooled or carried between calls.

It is also self-contained. A profile declares everything it needs, relative paths resolve against the config file, and nothing is inherited from the machine it happens to run on — no ssh-agent, no ~/.ssh/config, no ambient environment. Copy the config directory to a server or a container and it behaves identically.

It speaks JSON-RPC over stdio, so it drops into any MCP harness: Claude Code, Codex, opencode, Cursor, Zed, and anything else that can spawn a command.

Status: the config, policy and SSH layers are covered by tests, including real SSH handshakes against a local test server. It has not yet been run against physical MikroTik hardware — run mikrotik-mcp --test <profile> against your own router first. Please report anything RouterOS does differently.

Use it

npx -y @denver6000/mikrotik-mcp

The published package is plain Node ESM with no runtime toolchain of its own — Node 18+ is enough.

If a profile uses password auth, the client also has to pass the variable holding it — see Getting a secret to the server.

Related MCP server: mikrotik-cli-mcp

Quick start

1. Prepare the router

Create a dedicated RouterOS user rather than reusing admin. A read-only group is the real safety mechanism — the server's own readOnly check is only a guardrail.

/user group add name=mcp-read policy=ssh,read,test
/user add name=mcp-readonly group=mcp-read
/ip service enable ssh

Then give it a key (preferred) or a password:

# key auth — upload your public key first, e.g. with scp
/user ssh-keys import public-key-file=id_mikrotik.pub user=mcp-readonly

# or password auth
/user set mcp-readonly password="..."

2. Write a config file

Start from config.example.json. For a first router, put this at ~/.mikrotik-mcp.json:

{
  "profiles": {
    "core": {
      "host": "10.0.0.1",
      "username": "mcp-readonly+ct",
      "auth": { "type": "key", "path": "./keys/mikrotik" },
      "description": "Core router"
    }
  }
}

./keys/mikrotik resolves against the config file's own directory, not the working directory — so a folder holding the config and its keys can be moved anywhere and still work.

Everything else defaults: port 22, known_hosts verification, read-only, 20 s timeout. The +ct suffix tells RouterOS to drop colour codes and paging.

auth has no default and must be declared. That is deliberate: guessing at an agent or a conventionally-named key would make the config depend on the machine it runs on, which is exactly what this server avoids.

3. Trust the host key

The first connection will be refused, on purpose, because the router is not in known_hosts yet. Either add it the normal way:

ssh-keyscan -H 10.0.0.1 >> ~/.ssh/known_hosts

…or, if you prefer to pin the key in the config, run the command once and copy the fingerprint out of the error message into hostKey.fingerprintSha256. Verify the fingerprint against the router itself (/ip ssh print shows the host key, or read it on the console) before trusting it.

4. Check it

npx -y @denver6000/mikrotik-mcp --check-config

Config search path (highest precedence first):
         C:\work\.mikrotik-mcp.json
  loaded C:\Users\you\.mikrotik-mcp.json

Profiles (1):
  core
    ssh       mcp-readonly+ct@10.0.0.1:22
    auth      agent
    host key  known-hosts
    writes    refused (readOnly)
    from      C:\Users\you\.mikrotik-mcp.json

This exits non-zero if a file is unparseable or no profiles were found, so it works in CI too. It reads the same files the server does, but connects to nothing.

5. Prove it against the router

--check-config never connects to anything. To test the whole path — TCP, host key, credentials, RouterOS — run:

npx -y @denver6000/mikrotik-mcp --test core

Connecting to 'core' (mcp-readonly+ct@10.0.0.1:22) as agent...
  host key   SHA256:9lK…  (accepted by policy 'known-hosts')
  command    /system identity print
  exit code  0
  took       412ms

  name: MikroTik-core

OK.

It runs one harmless read (/system identity print), prints FAILED. with the reason if anything goes wrong, and exits non-zero. Do this before wiring up an agent — it tells you whether a problem is in the config, the network, or the router.

6. Point your agent at it

Ask it to run /system resource print on core. It should call mikrotik_list_profiles first, then mikrotik_exec.

Configuration

defaults applies to every profile in the same file; a profile overrides it field by field.

{
  "$schema": "https://raw.githubusercontent.com/denver6000/mikrotik-mcp/main/schema/mikrotik-mcp.schema.json",
  "defaults": {
    "username": "mcp-readonly+ct",
    "auth": { "type": "agent" },
    "timeoutMs": 20000
  },
  "profiles": {
    "core": {
      "host": "10.0.0.1",
      "description": "Core router, main uplink",
      "tags": ["core", "site-a"]
    },
    "branch-a": {
      "host": "192.168.50.1",
      "port": 2222,
      "tags": ["branch", "site-b"],
      "hostKey": { "policy": "pinned", "fingerprintSha256": "SHA256:abc..." }
    },
    "lab": {
      "host": "10.20.0.1",
      "username": "admin+ct",
      "auth": { "type": "password", "passwordEnv": "MIKROTIK_LAB_PASSWORD" },
      "readOnly": false
    }
  }
}

Adding $schema gives you completion and validation in any editor that speaks JSON Schema.

Profile fields

Where the config is read from

Every one of these is loaded, highest precedence first. When two files define the same profile name the earlier one wins; profiles with different names merge into one list.

Which to use:

• One personal file — ~/.mikrotik-mcp.json. Fine for most people; start here.

• Per-repo file — .mikrotik-mcp.json committed alongside a network-automation repo, so anyone cloning it gets the right profiles. Safe to commit: it holds no secrets. Because parents are searched too, a file at the root of a monorepo covers every package under it.

• Both — the repo file wins for names it defines, and your personal file supplies the rest. This is how you override one router's settings locally without editing a shared file.

• An explicit path — $MIKROTIK_MCP_CONFIG for CI, or to keep several environments in separate files: MIKROTIK_MCP_CONFIG=prod.json:staging.json.

Files are re-read on every tool call, so edits take effect without restarting the server or the agent. mikrotik_list_profiles reports which file each profile came from and flags any it could not parse.

Authentication

Every profile declares an auth block. There is no implicit fallback.

{ "type": "key", "path": "./keys/mikrotik" }                     // recommended
{ "type": "key", "path": "./keys/mikrotik", "passphraseEnv": "MTK_KEY_PASS" }
{ "type": "password", "passwordEnv": "MIKROTIK_LAB_PASSWORD" }
{ "type": "agent" }                                              // opt-in; see the caveat below
{ "type": "agent", "socket": "/run/user/1000/ssh-agent" }

Secrets never go in the config file. A profile names the environment variable holding a password or passphrase, and the value is read at connect time — so config files stay safe to commit and share.

Paths expand ~ and $VARS; anything still relative resolves against the config file's directory.

Key formats

ssh2 does not accept every key file OpenSSH can. Verified against ssh2 1.17:

In practice: generate keys with ssh-keygen -t ed25519 and you will never hit this. If you have a PKCS#8 key, --check-config names the problem and prints the conversion command rather than failing at connect time with "Unsupported key format".

Encrypted keys and the agent

Without an agent, an encrypted key's passphrase has to come from an environment variable — which runs into the subprocess problem below. So a self-contained setup in practice means a dedicated, unencrypted key file.

That is the standard automation answer, and it is safe here only because the blast radius is bounded elsewhere: the key belongs to a RouterOS user in a read-only group, it is used for nothing else, and it sits with chmod 600. On POSIX systems --check-config warns if the file is readable by group or others.

Agent auth remains supported for anyone who prefers it, but it is opt-in and not the default. It ties the profile to the environment the server was launched from: SSH_AUTH_SOCK is not always inherited by a subprocess spawned from a GUI application, and there is no agent at all in a typical container.

Getting a secret to the server

Your MCP client launches this server as a subprocess, so a variable exported in your interactive shell does not necessarily reach it. Either use agent or key auth — which need no variables, and are the reason agent is the default — or declare the variable in the client's own config. The field differs per client:

# Claude Code
claude mcp add mikrotik --env MIKROTIK_LAB_PASSWORD=... -- npx -y @denver6000/mikrotik-mcp

# Codex — ~/.codex/config.toml
[mcp_servers.mikrotik]
command = "npx"
args = ["-y", "@denver6000/mikrotik-mcp"]
env = { MIKROTIK_LAB_PASSWORD = "..." }

// opencode — note "environment", not "env"
{
  "mcp": {
    "mikrotik": {
      "type": "local",
      "command": ["npx", "-y", "@denver6000/mikrotik-mcp"],
      "enabled": true,
      "environment": { "MIKROTIK_LAB_PASSWORD": "..." }
    }
  }
}

// generic mcpServers config
{
  "mcpServers": {
    "mikrotik": {
      "command": "npx",
      "args": ["-y", "@denver6000/mikrotik-mcp"],
      "env": { "MIKROTIK_LAB_PASSWORD": "..." }
    }
  }
}

Note the trade-off: this moves the password out of the router config and into the client config, which is usually not a file you want to commit either. Key or agent auth avoids the problem entirely.

Host key verification

On by default. A router whose key is unknown is refused, and the error prints the fingerprint so you can verify it and then trust it.

{ "policy": "pinned", "fingerprintSha256": "SHA256:abc..." }      // self-contained; preferred
{ "policy": "known-hosts" }                                       // default
{ "policy": "known-hosts", "knownHostsPath": "./known_hosts" }
{ "policy": "insecure-ignore" }                                   // accept anything — lab use only

Under the default known-hosts policy, a known_hosts file beside the config is consulted first, then ~/.ssh/known_hosts as a fallback. Naming knownHostsPath explicitly uses that file only. For a config that must be portable, either ship a known_hosts next to it or pin the fingerprint — the personal-file fallback is a convenience for a workstation, not something to depend on. --check-config prints exactly which files will be consulted.

Setting fingerprintSha256 without a policy implies pinned. Hashed known_hosts entries, wildcards, [host]:port entries and negated patterns are all handled. A host that is known but presents a different key is a hard failure, never a prompt.

Older routers: legacy crypto

Modern SSH clients no longer enable the key exchange and host key algorithms that older RouterOS releases — or routers with strong crypto disabled — may be limited to. If the connection fails during handshake rather than at login, add what that router needs:

{
  "host": "10.0.0.1",
  "algorithms": {
    "kex": { "append": ["diffie-hellman-group14-sha1"] },
    "serverHostKey": { "append": ["ssh-rsa"] }
  }
}

append, prepend and remove are passed through to the SSH layer, as are plain arrays if you want to specify the whole list. Prefer upgrading RouterOS or enabling strong crypto on the router over weakening the client.

Read-only by default

Profiles are readOnly: true unless you say otherwise. Commands are classified before connecting: a command must contain a recognised read action (print, get, find, export, monitor, ping, …) and no recognised write action (set, add, remove, reboot, …). Every command in a ;- or newline-separated chain is checked, so a read cannot smuggle a write along with it. Anything the classifier does not understand is treated as a write and refused.

This is a guardrail against accidents, not a security boundary. A determined agent, or a command phrased in a way the classifier does not model, can get past it. For real enforcement, log in as a RouterOS user whose group grants read access only — the router is the only thing that can enforce that. Set readOnly: false on profiles where writes are intended.

Troubleshooting

RouterOS reference

Four documents ship with the package and back mikrotik_search_docs:

Content is written for this project rather than copied from MikroTik, and each claim was checked against the official documentation. Where something is widely used but could not be confirmed — print terse and print as-value — it is labelled as unverified rather than presented as fact. Verify those against your hardware.

The trap worth knowing

RouterOS item numbers are assigned per session and reassigned on the next print. Since every mikrotik_exec call is its own SSH session, a number from one call is meaningless in the next — and acting on a stale number does not error, it acts on whatever holds that number now. Always select by predicate:

/ip firewall filter remove [find where comment="mcp-temp"]

This is stated in the mikrotik_exec tool description as well as the reference, because it is the most expensive thing an agent can get wrong here.

Command line

Tools

mikrotik_list_profiles

Search the configured routers. Returns connection details, which config file each came from, whether it is read-only, and any config problems. Never returns secrets — only the name of the variable holding one.

mikrotik_search_docs

Search bundled RouterOS reference material — command syntax, idioms, and v6/v7 differences. Offline and read-only; it touches no router and needs no config.

The reference lives in docs/ as plain markdown and is re-read on every call, so it can be edited or extended without rebuilding. Ranking is BM25 over sections, with no dependencies and no index to keep in sync.

mikrotik_exec

Run one RouterOS command on one router and return its output.

Returns stdout, stderr, the exit code and the host key fingerprint, as text and as structured content. Because each call is a fresh connection with no shell state, commands must use absolute RouterOS paths (/ip address print, not print after a cd).

Develop

No extra toolchain: Node runs the TypeScript sources directly via built-in type stripping, so npm install is the whole setup. Node 22.18+ is required for development; the published package supports Node 18+.

npm install
npm run dev         # run the server on stdio, straight from src/
npm test            # unit tests + a real SSH round-trip against a local ssh2 server
npm run typecheck
npm run schema      # regenerate schema/mikrotik-mcp.schema.json from the zod schema
npm run build       # emit dist/ with tsc
npm run inspect     # open the MCP Inspector against src/

Layout

src/
  index.ts             CLI entry: arg handling + stdio transport
  server.ts            createServer() — registers every tool
  config/
    schema.ts          zod schema for the config file, and the resolved profile type
    paths.ts           where config files are looked for; ~ and $VAR expansion
    load.ts            read, validate, merge, search
    report.ts          the --check-config report
  docs/
    corpus.ts          parse docs/*.md into searchable sections
    search.ts          dependency-free BM25 ranking
  ssh/
    exec.ts            one connection, one command, then close
    knownHosts.ts      known_hosts parsing and host key verification
    policy.ts          read-only command classification
    keyFile.ts         offline key inspection: format, fingerprint, permissions
    testConnection.ts  the --test <profile> probe
  tools/
    listProfiles.ts    mikrotik_list_profiles
    exec.ts            mikrotik_exec
    searchDocs.ts      mikrotik_search_docs
docs/                  the RouterOS reference, shipped with the package
scripts/
  generate-schema.ts   zod schema -> JSON Schema
test/                  node:test suites; helpers.ts builds a sandboxed config + env

Every entry point takes an injectable LookupEnvironment (env, cwd, home, platform) so tests never touch the real user's config or SSH agent.

Adding a tool

1. Add src/tools/<name>.ts exporting a register…Tool(server, e) function.

2. Call it from createServer() in src/server.ts.

3. Add a case to test/server.test.ts.

Relative imports use explicit .ts extensions so Node can run the sources as-is; tsc rewrites them to .js on build. Keep stdout clean — it is the JSON-RPC channel. Log to stderr only.

Release

The npm package is @denver6000/mikrotik-mcp. It is scoped because the unscoped mikrotik-mcp is taken by an unrelated project; the installed command is still mikrotik-mcp.

version lives in both package.json and SERVER_VERSION in src/server.ts; bump both. A test fails if they disagree, and the release workflow fails if the git tag disagrees with either.

First publish

Trusted publishing cannot do a package's first release: a trusted publisher is configured on a package that already exists. So one release goes out from a workstation, and every release after that is automated.

It does not need an access token. npm warns against tokens with 2FA bypass for automation, and they are unnecessary here — modern npm authenticates in the browser, which works with a passkey, Windows Hello, Touch ID or a security key:

npm logout          # clears any stored _authToken from ~/.npmrc
npm login           # opens a browser; npm 9+ defaults to auth-type=web
npm whoami          # must print denver6000 — the scope has to match
npm publish

A stored _authToken in ~/.npmrc is the usual reason this fails with E403 ... Two-factor authentication or granular access token with bypass 2fa enabled is required: npm presents the token instead of starting an interactive login, and a token without 2FA bypass cannot publish. npm logout removes it, after which the browser flow takes over.

If your second factor is an authenticator app rather than a passkey, npm publish --otp=123456 also works.

Then switch CI on (once)

On npmjs.com, open the package → Settings → Trusted publisher, and add a GitHub Actions publisher:

After that, every later release is a tag push, with no npm token stored anywhere:

npm version patch       # or minor / major — commits and tags
git push --follow-tags

.github/workflows/release.yml then runs typecheck, tests and build, checks the tag against package.json, and publishes over OIDC. Provenance is attached automatically, so the package page links back to the exact commit and workflow run that built it.

Only dist/, docs/, schema/, README.md and LICENSE are published.

License

MIT