# Fluent MCP server

> Enables AI agents to develop ServiceNow applications using the Fluent SDK through CLI tools, API specifications, and automated security and performance reviews.

- Repository: https://github.com/modesty/fluent-mcp
- Page: https://hostedmcp.org/servers/modesty/fluent-mcp
- Transport: stdio
- Stars: 33
- License: MIT

## Install

### Claude Code

```sh
claude mcp add fluent-mcp -- npx -y @modesty/fluent-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "fluent-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@modesty/fluent-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "fluent-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modesty/fluent-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"fluent-mcp","type":"stdio","command":"npx","args":["-y","@modesty/fluent-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "fluent-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@modesty/fluent-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add fluent-mcp -- npx -y @modesty/fluent-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.fluent-mcp]
command = "npx"
args = ["-y", "@modesty/fluent-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user fluent-mcp npx -- -y @modesty/fluent-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "fluent-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@modesty/fluent-mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `FLUENT_MCP_WORKING_DIR` | no | no |  |
| `SN_AUTH_TYPE` | no | no |  |
| `SN_INSTANCE_URL` | no | no |  |

## Tools (16)

- `build_fluent_app`: Build a Fluent (ServiceNow SDK) application package from source code. Requires a valid Fluent project directory with now.config.json. Run after init_fluent_app and before deploy_fluent_app. Does NOT require instance authentication.
- `check_auth_status`: Check current ServiceNow authentication status. Lazily validates configured auth once and returns JSON including status, profile alias, instance host, auth type, and any required user action. Call this before commands that require authentication (deploy_fluent_app, fluent_transform, download_fluent_dependencies, download_fluent_app) to verify credentials are configured. (read-only)
- `cicd_fluent_app`: Run a ServiceNow app-repo CI/CD operation via the sn_cicd API (SDK v4.10.0+): install, publish, or rollback an application on an instance. CHANGES INSTANCE STATE. Identify the app with either scope or appSysId; inside a Fluent project both appSysId and appVersion default from now.config.json/package.json, and outside one both must be passed explicitly. appVersion is always required for rollback. Requires instance authentication (auto-injected from session, or pass auth explicitly).
- `cicd_fluent_test`: Run or inspect ServiceNow ATF tests through the sn_cicd API (SDK v4.10.0+). Set target to "testsuite" or "test" and action to "run" (start it), "watch" (follow a progressId from a previous run), "result" (fetch a resultId), or "logs" (fetch the captured logs of a single test result, optionally filtered by a regex pattern; target="test" only, SDK v4.12.0+). Identify a suite by testSuiteSysId or testSuiteName, a test by testSysId or testName. action="run" executes real ATF steps on the instance and the records those steps touch change; "watch", "result", and "logs" only read. No Fluent project required. Requires instance authentication (auto-injected from session, or pass auth explicitly).
- `clean_fluent_app`: Delete the build output directory of a Fluent (ServiceNow SDK) application. This is a destructive operation that removes all compiled artifacts. Run build_fluent_app afterward to regenerate. Does NOT require authentication.
- `deploy_fluent_app`: Deploy a built Fluent (ServiceNow SDK) application to a ServiceNow instance. Requires a prior build via build_fluent_app and valid instance authentication (auto-injected from session, or pass auth explicitly). Use skipFlowActivation to prevent auto-publishing of flows and subflows during deployment. Since SDK v4.12.0 the install runs asynchronously by default (the CLI polls the instance until it finishes); set async=false to force a synchronous install.
- `download_fluent_app`: Download application metadata from a ServiceNow instance into a local directory. Includes metadata deployed to the instance that may not exist locally. The directory argument specifies where to expand the application. Use incremental mode to download only changes since the last download. For a large application, raise timeoutSeconds (SDK v4.13.0+). Requires instance authentication (auto-injected from session).
- `download_fluent_dependencies`: Download configured dependencies from now.config.json and TypeScript type definitions for use in a Fluent application. Requires instance authentication (auto-injected from session, or pass auth explicitly). Supports pulling type definitions for tables and roles outside application scope via dependencies.global configuration. Run this after init_fluent_app to set up type definitions before development.
- `explain_fluent_api`: Look up Fluent SDK documentation for any API or guide. Accepts a topic name (e.g., "BusinessRule", "Acl") or a keyword/tag (e.g., "flow", "atf"). Set list=true to enumerate available topics (optionally combined with topic to filter). Set peek=true for a brief summary. Set format="raw" for plain markdown. Read-only; no authentication or active Fluent project required. Use get_fluent_knowledge for metadata-type specifications, authoring guides and code examples. (read-only)
- `fluent_exec_script`: Run a server-side JavaScript script on the authenticated ServiceNow instance, like the Scripts - Background page (SDK v4.14.0+ `now-sdk exec`). The script runs with the authenticated user's full permissions and needs the admin role. BEFORE EVERY CALL: show the user the full script, the target instance, the scope, and the reason, and get their explicit approval for that run; approval of one script never covers another. With file, show the file's full CONTENT, not just its path, and do not edit the file between approval and the call; the result echoes the content and SHA-256 that actually ran. Prefer query_fluent_records for reads and the app's own metadata for anything that should ship with the app. The run is recorded in Script Execution History with a rollback context, but rollback only reverts record changes; emails, REST calls, events and scheduled jobs it triggers cannot be undone. A timeout or cancellation does NOT stop the script on the instance; never retry automatically, or a second copy runs. ok: false with an errors array means the script RAN and threw, possibly after changing records, so a retry runs it again; ok: false with error.message means it never ran (for example an unknown scope). Returns a JSON envelope with ok, output, errors, scope, executionHistoryId, and rollbackContextId (absent when no records changed or the history record is unreadable). Requires instance authentication (auto-injected from session, or pass auth explicitly).
- `fluent_transform`: Convert XML metadata into Fluent source code, or pull changes made on a ServiceNow instance back into the project's .now.ts files. Use from for local XML files/directories (offline; cannot be combined with auth or id). Omit from to pull the whole application from the instance (auth auto-injected from session, or pass auth). Use table with id (SDK v4.7.0+) to pull one record and its related records from the instance. table without id only filters local XML (from, or the project directory) to those tables and their descendants — it does not download, though the CLI still requires credentials when from is omitted. For a large full-application pull, raise timeoutSeconds (SDK v4.13.0+). Overwrites local changes to the records it updates.
- `get_fluent_knowledge`: Read Fluent knowledge for a ServiceNow metadata type (e.g., business-rule, script-include). kind 'spec' returns the Fluent API specification, 'instruct' the authoring rules, conventions and pitfalls, and 'snippet' a runnable code example (without snippetId, the first one plus the ids of the others). Omit metadataType to list the metadata types that have that kind. For SDK APIs and guides beyond metadata types, use explain_fluent_api. (read-only)
- `init_fluent_app`: Initialize a new Fluent (ServiceNow SDK) application or convert an existing scoped application. Set intent to "creation" for a new app (requires appName, packageName, scopeName, template) or "conversion" to convert from an instance sys_id or an absolute local application directory (requires from, and auth for instance conversion; pass packageName too, or the returned command prompts for it). Creation is not offline: the returned command reads the vendor prefix of the auth instance (explicit, else the session alias, else the CLI default profile) and contacts the npm registry. The workingDirectory must be an absolute path to an empty directory, or to a new directory under an existing one. The result is a shell command that enters that directory and runs the SDK init. After init, use build_fluent_app to compile.
- `pack_fluent_app`: Package a built Fluent (ServiceNow SDK) application into a zip artifact for installation. Requires a prior build via build_fluent_app. The output zip can be used for manual installation on a ServiceNow instance. Does NOT require authentication.
- `query_fluent_records`: Run a read-only query against a ServiceNow table via the Table REST API (SDK v4.8.0+). Returns matching records as a JSON envelope. Requires instance authentication (auto-injected from session, or pass auth explicitly). Provide table and an encoded query (e.g. "active=true^priority<=2"). No Fluent project required. (read-only)
- `sdk_info`: Get Fluent (ServiceNow SDK) version or help information. Use -v to check the installed SDK version, or -h for general help or help on a specific command (e.g., flag: "-h", command: "build"). Does NOT require authentication or a Fluent project directory. (read-only)

## FAQ

### How do I set up the Fluent MCP server?

Add @modesty/fluent-mcp to your MCP client configuration using npx, ensuring you provide the required environment variables like SN_INSTANCE_URL.

### What AI agent skills are available?

The suite includes skills for CLI workflows, security reviews, general best-practice reviews, performance reviews, and domain separation/MSP readiness reviews.

### Can I use this for headless CI/CD pipelines?

Yes, you can set SN_SDK_NODE_ENV=SN_SDK_CI_INSTALL along with necessary credentials to use it in CI/CD environments.
