SNMP4J MCP Server README

snmp4j-mcp is a Model Context Protocol (MCP) server that exposes SNMP and SMI/MIB capabilities to MCP-compatible clients (LLM agents, the MCP Inspector, IDE assistants, …). It is built on SNMP4J and the SNMP4J-SMI-PRO MIB engine. The server communicates over stdio using the MCP protocol.

It provides:

• Tools for querying and compiling MIB modules, generating and sending SNMP PDUs, walking subtrees, reading tables, parsing raw SNMP messages, and detecting agent MIB support.
• Resources that publish JSON Schemas describing every tool's request and response payloads, plus dynamic resources for MIB module/object definitions and SNMP target configurations.
• Contexts that bind the tools to a MIB model repository and to configured SNMP targets.

---

Table of contents

• Requirements
• Building
• Running the server
• Command-line options
• Configuration
• Tools
• Resources
• Resource templates
• Contexts
• JSON definition files in the distribution
• Distribution layout

---

Requirements

• Java 21 or later (the code uses records and text blocks).
• A valid SNMP4J-SMI-PRO license key (required for the MIB/SMI features).
• Optionally, an OPENAI_API_KEY (or openai.api.key system property) to enable the semantic MIB search tool. Without it, a local ONNX embedding model is used if the DJL ONNX dependencies are on the classpath.

Building

mvn package

This produces a self-contained jar-with-dependencies and the distribution ZIP (via the assembly.xml descriptor). After building, the runnable jar is available as snmp4j-mcp.jar.

Running the server

The server is a stdio MCP server. It is normally launched by an MCP client, but you can also run it directly or attach the MCP Inspector:

# Show usage help
java -jar snmp4j-mcp.jar --help

# Run with an explicit configuration file
java -jar snmp4j-mcp.jar --config ./.snmp4j-mcp-config.json

# Launch under the MCP Inspector (see snmp4j-mcp-on-mcp-inspector.sh)
./snmp4j-mcp-on-mcp-inspector.sh snmp4j-mcp.jar

Diagnostic output is appended to .snmp4j-mcp-log in the working directory (stdout/stderr are reserved for the MCP stdio transport).

Command-line options

Option	Argument	Description
--config	<file>	Path to the JSON configuration file. When omitted, the server looks for .snmp4j-mcp-config.json in the current working directory.
--license	<key>	SNMP4J-SMI-PRO license key. Overrides the License entry of the configuration file.
--repoPath	<path>	Path to the MIB repository directory. Overrides the MIB.repositoryPath entry of the configuration file.
--port	<port>	TCP port (reserved for future network transports; the default stdio transport does not use it). Default: 8090.
--help, -h		Show usage help and exit.

Configuration

The server is configured through a JSON file (default .snmp4j-mcp-config.json). An annotated example is shipped in the distribution as doc/json/SNMPConfiguration.json:

{
  "License": { "license": "<Put SNMP4J-SMI-PRO license key here>" },
  "MIB": {
    "repositoryPath": "../snmp4j-smi/mibrepository",
    "moduleNames": ["SNMPv2-MIB", "IF-MIB"],
    "maxModuleLoadThreads": "auto"
  },
  "SNMP": [
    {
      "targetName": "default",
      "address": "udp:example.com/161",
      "community": "public",
      "retries": 1,
      "timeout": 5000,
      "version": "v3",
      "maxSizeResponsePdu": 65535,
      "SNMPv3": { "securityName": "user1", "authProtocol": "SHA256", "authPassphrase": "...",
                  "privProtocol": "AES128", "privPassphrase": "...", "securityLevel": "authPriv",
                  "contextName": "", "contextEngineID": "", "authoritativeEngineID": "" }
    },
    {
      "targetName": "tlsAgent",
      "address": "tls:example.com/10161",
      "retries": 1,
      "timeout": 5000,
      "version": "v3",
      "TLS": { "keyStore": "client-keystore.jks", "keyStorePassword": "...",
               "trustStore": "client-truststore.jks", "trustStorePassword": "...",
               "localId": "client", "peerId": "CN=agent,OU=snmp4j,O=SNMP4J.org,C=DE",
               "peerHostId": "example.com", "trustCa": "CN=ca,OU=snmp4j,O=SNMP4J.org,C=DE",
               "securityName": "tlsUser", "tlsVersion": "TLSv1.3,TLSv1.2" }
    }
  ]
}

Top-level configuration sections:

• License – the SNMP4J-SMI-PRO license key.
• MIB – repositoryPath (MIB repository directory), moduleNames (regular-expression patterns of modules to load on startup), maxModuleLoadThreads ("auto" or an integer), and the optional autoCompletionMaxElements (max entries returned by auto-completion; default 100, <= 0 disables the limit).
• SNMP – an array of named target configurations. Each target has a unique targetName, an address, transport/protocol settings (community, retries, timeout, version, maxSizeResponsePdu) and optional SNMPv3 and TLS sub-objects.

Security note: When an SNMP target configuration is exposed via the snmp/target/{targetName} resource, all properties whose names end in Passphrase, Password, or Key are stripped from the response to avoid leaking credentials.

Secure transports: tls: and dtls:

A target whose address starts with tls: (RFC 6353, TLS over TCP) or dtls: (RFC 5953, DTLS over UDP) is built as a certified target that uses the Transport Security Model (TSM, RFC 5591) instead of USM. Such a target requires "version": "v3" and takes all of its security parameters from its TLS sub-object:

Property	Scope	Description
keyStore / keyStorePassword	transport	Key store with the private key and certificate of this command generator. Falls back to javax.net.ssl.keyStore[Password].
trustStore / trustStorePassword	transport	Trust store with the trusted (CA) certificates. Falls back to javax.net.ssl.trustStore[Password].
localId	transport	Alias of the local certificate in keyStore; used as localCertificateAlias unless that is set explicitly.
localCertificateAlias	transport	Alias that selects a single certification chain from keyStore for client authentication.
tlsVersion	transport	Comma-separated TLS versions in descending preference for tls: addresses, e.g. "TLSv1.3,TLSv1.2" (default TLSv1.2).
dtlsVersion	transport	Comma-separated DTLS versions for dtls: addresses, e.g. "DTLSv1.2" (default DTLSv1.2).
endpointIdentificationAlgorithm	transport	JSSE endpoint identification algorithm, "HTTPS" by default. Set it to "" to disable JSSE host name verification, which is needed for fingerprint-pinned certificates without a matching subject alternative name.
crlURI	transport	URI of an X.509 certificate revocation list consulted during certification path validation.
revocationCheckOptions	transport	Names of PKIXRevocationChecker.Option constants, e.g. ["PREFER_CRLS","ONLY_END_ENTITY","NO_FALLBACK"]. An empty array enables revocation checking with the SNMP4J defaults; omitting the property installs no revocation checker.
maxFragmentSize	transport	Maximum TLS fragment size (RFC 6066 §4), tls: only.
maxInboundMessageSize	transport	Maximum size of an inbound SNMP message in bytes.
dtlsHandshakeTimeout	transport	DTLS handshake timeout in milliseconds (default 5000).
dtlsConnectionTimeout	transport	Idle timeout of a DTLS connection in milliseconds (default 300000).
peerId	target	Subject DN the peer certificate must have to be accepted, e.g. "CN=agent,OU=snmp4j,O=SNMP4J.org,C=DE".
trustCa	target	Issuer DN accepted for the peer certificate chain.
peerHostId	target	Identity the peer has to prove with its certificate (snmpTlstmAddrServerIdentity, RFC 6353 §5.3.1), matched against the dNSName/iPAddress subject alternative names of the peer certificate. Defaults to securityName.
securityName	target	The tmSecurityName of the target. Defaults to SNMPv3.securityName.
securityLevel	target	noAuthNoPriv, authNoPriv or authPriv. Defaults to SNMPv3.securityLevel and then to authPriv.
serverFingerprint	target	Hexadecimal fingerprint of the pinned server certificate (colons optional).
clientFingerprint	target	Hexadecimal fingerprint of the local certificate to present.
localEngineID	session	Local SNMP engine ID (hexadecimal) used by TSM. A random engine ID is generated when not configured.
tsmUsePrefix	session	The snmpTsmConfigurationUsePrefix flag of RFC 5591 §5.

Properties marked transport configure the TLSTM/DTLSTM transport mapping. Targets that agree in all transport properties share one transport mapping; targets that differ in any of them get their own, and every target is bound to its transport mapping. Properties marked target are carried by the target itself, so targets with different peers can share a transport mapping. Properties marked session are established once per SNMP session by the first target that needs them.

If neither peerId nor trustCa is configured, the peer certificate is accepted by certification path validation against trustStore alone — in addition to the fingerprint pinning and the endpoint identification that serverFingerprint and peerHostId impose.

---

Tools

All tools share the version 0.1.0. The "Context" column lists the contexts that must be ready for the tool to operate (see Contexts).

Tool name	Title	Context	Purpose
find_mib_objects	Find MIB Objects by search criteria	model-repository	Keyword/OID/regex MIB search
check_mib	Check MIB Syntax	model-repository	Validate a MIB (dry run)
check_mib_completely	Check MIB Syntax (Complete)	model-repository	Validate a MIB without error limit
compile_mib	Compile and Store MIB	model-repository	Compile and persist a MIB
snmp_command_generator	SNMP Command Generator	snmp-agent	Send an arbitrary SNMP PDU (JSON)
snmp_set	SNMP Get / Set	snmp-agent	Plain-text GET / SET
snmp_get_table	SNMP Get Table	snmp-agent	Retrieve tabular data
snmp_walk_subtree	SNMP Walk Subtree	snmp-agent	Walk a subtree via GETNEXT/GETBULK
snmp_message_ber	SNMP Message BER Parser	–	Decode a raw SNMP message
snmp_detect_mib_modules	SNMP MIB Module Support Detection	snmp-agent	Detect which MIBs a target implements
semantic_search_mib	Semantic MIB Search	–	Natural-language vector search over MIBs

find_mib_objects — Find MIB Objects by search criteria

Search for MIB definitions, modules, and objects using OIDs, names, types, and regular expressions.

Parameter	Type	Required	Description
operation	string	yes	One of findSmiObject, findSmiObjectType, findRootSmiObject, findSmiModule, findSmiModules, findSmiObjectByName, findSmiObjectsByType, findSmiObjectsByRegexMatching.
oid	string	no	OID for OID-based searches (findSmiObject, findSmiObjectType).
moduleName	string	no	MIB module name (e.g. SNMPv2-MIB); if omitted, all modules are searched.
objectName	string	no	Object name to search for (findSmiObject / findSmiObjectType).
includeImportedModules	boolean	no	Whether to search imported modules (default false).
type	string	no	SMI type filter (e.g. OBJECT_TYPE, OBJECT_TYPE_SCALAR, OBJECT_TYPE_TABLE, NOTIFICATION_TYPE).
smiObjectJsonPattern	string	no	JSON object of property→regex pairs matched against SmiObject properties. Schema: resource://snmp4j/schema/SmiObjectJsonSchema.json.

check_mib / check_mib_completely / compile_mib — MIB Compiler

Three tools backed by the same compiler with different target modes:

• check_mib — Check MIB Syntax. Check a MIB specification for SMIv1/v2 syntax and semantic errors without modifying the repository. Returns compilation results as JSON.
• check_mib_completely — Check MIB Syntax (Complete). Same as check_mib but without an error-count limit; returns all compilation results.
• compile_mib — Compile and Store MIB. Compile, validate, and persist the result into the repository without loading it into the in-memory MIB cache.

Parameter	Type	Required	Description
mibContent	string	yes	The MIB specification text (SMIv1 or SMIv2). Result schema: resource://snmp4j/schema/CompilationResultJsonSchema.json.
fileName	string	no	Logical name for the MIB input (default unnamed.mib).
strictness	string	no	standard (default) or lenient.
overwriteMode	string	no	compile_mib only. addNewOnly (default), overwriteIfNewer, or overwriteAlways.

The full input schema is published as resource://snmp4j/schema/MibCompilerToolSchema.json and is also shipped in the distribution as doc/json/MibCompilerToolSchema.json.

snmp_command_generator — SNMP Command Generator

Sends an SNMP PDU (GET, GETNEXT, GETBULK, SET, INFORM) to a configured SNMP target and returns the response as JSON.

Parameter	Type	Required	Description
targetName	string	yes	Name of the configured SNMP target (see snmp/target/{targetName}).
pdu	string	yes	JSON object describing the PDU. Requires type (GET/GETNEXT/GETBULK/SET/INFORM) and variableBindings (array of {oid, type, value}). For GET* the value may be omitted; types are inferred from loaded MIBs when type is omitted.

• Request schema: snmp4j/schema/SnmpPduRequest.json
• Response schema: snmp4j/schema/SnmpResponseEvent.json
• Sample SET PDU (create an snmpTargetAddrEntry row): snmp4j/samples/SnmpPduRequest-snmpTargetAddrEntry-createRow.json

snmp_set — SNMP Get / Set

Sends an SNMP GET (default, read-only) or SET request to a configured target. Variable bindings are given as a plain-text list, one entry per line or comma (auto-detected).

Parameter	Type	Required	Description
targetName	string	yes	Name of the configured SNMP target.
variableBindings	string	yes	Newline- or comma-separated list. GET mode: each entry is an OID. SET mode: each entry is OID=value using SNMP4J string syntax (e.g. string:hello, integer:42, oid:1.3.6.1).
set	boolean	no	true to send a SET PDU; false (default) to send a read-only GET.

snmp_get_table — SNMP Get Table

Retrieves SNMP tabular data from a configured target and returns it as JSON. Row-retrieval progress is reported to the MCP client during the operation.

Parameter	Type	Required	Description
targetName	string	yes	Name of the configured SNMP target.
columnOIDs	string	yes	Comma-separated columnar OIDs (must be column objects, not instances).
lowerBoundIndex	string	no	Lower-bound row index OID (exclusive).
upperBoundIndex	string	no	Upper-bound row index OID (inclusive).
contextName	string	no	SNMPv3 context name (UTF-8); ignored for v1/v2c.
contextEngineID	string	no	SNMPv3 context engine ID (lower-case hex); ignored for v1/v2c.
timeoutSeconds	integer	no	Max wait time; 0 = wait indefinitely.
maxRows	integer	no	Max rows to return; 0 = no limit.
includeOids	boolean	no	Include each cell's full instance OID (default false).

Response schema: snmp4j/schema/SnmpTableResult.json.

snmp_walk_subtree — SNMP Walk Subtree

Walks an SNMP subtree rooted at the given OID using GETNEXT (SNMPv1) or GETBULK (SNMPv2c/v3) and returns all variable bindings as JSON. Progress is reported to the MCP client during the walk.

Parameter	Type	Required	Description
targetName	string	yes	Name of the configured SNMP target.
rootOID	string	yes	Subtree root OID (the root itself is not included).
timeoutSeconds	integer	no	Max wait time; 0 = wait indefinitely.
maxVBs	integer	no	Max total variable bindings; 0 = no limit.
maxRepetitions	integer	no	Max bindings per GETBULK (ignored for v1); 0 = default (10).

Response schema: snmp4j/schema/SnmpTreeResult.json.

snmp_message_ber — SNMP Message BER Parser

Parses a raw SNMP message from a hex string and returns its BER structure as a text tree or JSON object tree. Supports SNMPv1/v2c/v3, including decryption of AUTH_PRIV messages when a matching SNMPv3 target with authoritativeEngineID is configured.

Parameter	Type	Required	Description
hexMessage	string	yes	Raw message as hex: colon-delimited (30:73:02:...), plain digits (307302...), or 0x-prefixed bytes.
outputAsJSON	boolean	no	true → JSON object tree; false (default) → indented text tree.
useSpecifiedTargetsOnlyForDecryption	string	no	Comma-separated SNMPv3 target names whose credentials are used for decryption. Empty → try all v3 targets with an authoritativeEngineID.

Response schema (when outputAsJSON is true): snmp4j/schema/SnmpBERResult.json.

snmp_detect_mib_modules — SNMP MIB Module Support Detection

Determines which loaded MIB modules are implemented by an SNMP target by probing table objects (via GETNEXT) and scalar objects (via GET). Returns the supported module names as a comma-separated list. MIB modules must be loaded on the server before calling this tool.

Parameter	Type	Required	Description
targetName	string	yes	Name of the configured SNMP target.
limit	integer	no	Max variable bindings per PDU (1–10, default 5).

semantic_search_mib — Semantic MIB Search

Performs semantic (vector-similarity) search over all loaded MIB objects using natural language. Understands synonyms and paraphrases (e.g. "interface throughput" matches ifSpeed and ifHighSpeed). Requires OPENAI_API_KEY (or the openai.api.key system property). The index is built on first use and cached; the first call after server start may take a minute.

Parameter	Type	Required	Description
query	string	yes	Natural-language description of what you are looking for.
limit	integer	no	Max results (1–100, default 10).
type	string	no	SmiType filter substring (e.g. OBJECT_TYPE_SCALAR, OBJECT_TYPE_COLUMN, OBJECT_TYPE_TABLE, NOTIFICATION_TYPE, TEXTUAL_CONVENTION, MODULE_IDENTITY).
syntax	string	no	SmiSyntax filter substring (e.g. OBJECT IDENTIFIER, OCTET STRING, Integer32, Gauge32, Counter32, Counter64, RowStatus, StorageType).

---

Resources

The server publishes the following static resources. Schema resources use the application/schema+json MIME type; samples use application/json.

URI	Title	Description
resource://snmp4j/schema/SmiObjectJsonSchema.json	SmiObject JSON Schema	Schema for SmiObject and all its sub-interfaces.
resource://snmp4j/schema/CompilationResultJsonSchema.json	CompilationResult JSON Schema	Schema for the result returned by the MIB compiler tools.
resource://snmp4j/schema/MibCompilerToolSchema.json	MibCompilerTool Input Schema	Input schema for check_mib, check_mib_completely, compile_mib.
snmp4j/schema/SnmpPduRequest.json	SNMP PDU Request Schema	Schema for the pdu parameter of snmp_command_generator.
snmp4j/schema/SnmpResponseEvent.json	SNMP Response Event Schema	Schema for the response of snmp_command_generator.
snmp4j/samples/SnmpPduRequest-snmpTargetAddrEntry-createRow.json	Sample: Create snmpTargetAddrEntry row (SET)	Sample SET PDU creating a row in snmpTargetAddrTable via createAndGo(4).
snmp4j/schema/SnmpTableResult.json	SNMP Table Result Schema	Schema for the response of snmp_get_table.
snmp4j/schema/SnmpTreeResult.json	SNMP Tree Result Schema	Schema for the response of snmp_walk_subtree.
snmp4j/schema/SnmpBERResult.json	SNMP BER Result Schema	Schema for the response of snmp_message_ber when outputAsJSON is true.

The schema/sample resources above are generated by the server at runtime and read through MCP resource reads. The MibCompilerToolSchema.json definition is additionally shipped on disk in the distribution under doc/json/ — see JSON definition files in the distribution.

Resource templates

Dynamic resources are exposed through URI templates with auto-completion support:

URI template	Title	MIME type	Description
mib/module/{moduleName}	MIB Module	text/plain	SMI/SNMP MIB module definition text for any loaded module.
mib/object/{moduleName}/{objectName}	MIB Object (module/name)	text/plain	SMI definition of a MIB object by module + object name.
mib/object/{oid}	MIB Object (OID)	text/plain	SMI definition of a MIB object by dotted-decimal OID.
snmp/target/{targetName}	SNMP Target	application/json	SNMP target configuration by unique target name (credentials are filtered out).

Contexts

Contexts gate the tools and bind them to server state. A tool's required contexts must be ready before it can be used.

Context ID	Name	Description
model-repository	Model Repository Context	Provides access to MIB and model definitions. Required by the MIB search and compiler tools.
snmp-agent	SNMP Agent Context	Provides access to SNMP agent (target) configuration and data. Required by the SNMP command/table/tree/detection tools.

---

JSON definition files in the distribution

For documentation and offline reference, the build copies the on-disk JSON definition resources into the doc/json/ directory of the distribution ZIP (configured in assembly.xml):

File	Description
doc/json/MibCompilerToolSchema.json	Input parameter schema for the MIB compiler tools (check_mib, check_mib_completely, compile_mib).
doc/json/SNMPConfiguration.json	Annotated example of the server configuration file structure (License, MIB, SNMP).

The remaining schemas listed under Resources (e.g. SnmpTableResult.json, SnmpTreeResult.json, SnmpPduRequest.json, SnmpResponseEvent.json, SnmpBERResult.json) are generated by the server at runtime and are obtained by reading the corresponding MCP resource.

Distribution layout

The assembled distribution ZIP has the following layout:

snmp4j-mcp.jar                         Runnable jar-with-dependencies
README.md / LICENSE-2,0.txt / NOTICE   Documentation and license files
doc/
  json/
    MibCompilerToolSchema.json         MIB compiler tool input schema
    SNMPConfiguration.json             Example server configuration
examples/
  config/                              Example configuration files
  input/                               Example tool inputs (e.g. SNMPv3 hex message)
  output/                              Example tool outputs (BER dump, JSON)
  mibs/                                Example MIB modules
  mibrepository/                       Example MIB repository with precompiled MIBs