mariana-mcp
MCP server for Mariana: lets AI assistants search and explore the relationships between people, companies, assets and legal cases in your connected data graph.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/santana-bigdata--mariana-mcp)HTML
<a href="/listings/santana-bigdata--mariana-mcp"><img src="/api/listings/santana-bigdata--mariana-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Open the Claude Code panel in VS Code (the spark icon, or **Claude Code: Open** in the command palette). 2. Type **`/plugins`** in the prompt box and press Enter. The **Manage plugins** window opens. 3. **Marketplaces** tab: type `Santana-BigData/mariana-mcp` and add it. 4. **Plugins** tab: search for **mariana**, click **Install** and choose **Install for you**. 5. A form asks for the plugin settings: paste your **Mariana API token** (`mrnk_…`). It is stored in your system's secure storage. Skipped it? Open the plugin's row and click the gear icon (or **Configure**). 6. Start a new conversation and type **`/mcp`**: `plugin:mariana:mariana` must show **Connected** (**Failed** means a wrong or revoked token). If the window says **Restart Claude to apply plugin changes**, do it.
> In the VS Code panel, typing `/plugin marketplace add …` or `/plugin install …` in the prompt box does **not** work ("isn't available in this environment"). Use the `/plugins` window above, or the terminal commands below.
Prefer the terminal? In VS Code's integrated terminal (needs the `claude` CLI installed; the extension doesn't add it to the PATH):
claude plugin marketplace add Santana-BigData/mariana-mcp claude plugin install mariana@mariana-mcp
The extension and the CLI share the same settings, so a plugin installed in one shows up in the other. Then open `/plugins` → **Plugins** → mariana → gear icon to set the token, and start a new conversation.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 19 lines
- {
- "name": "mariana-mcp",
- "owner": {
- "name": "Santana Big Data",
- "url": "https://mariana.santanabigdata.com.br"
- },
- "metadata": {
- "description": "Mariana graph database for Claude Code: MCP server and query skill."
- },
- "plugins": [
- {
- "name": "mariana",
- "source": "./plugins/mariana",
- "description": "Query the Mariana graph database from Claude Code (read-only MCP server + Cypher skill).",
- "category": "database",
- "tags": ["mcp", "graph", "database", "cypher"]
- }
- ]
- }
README.md · README · 135 lines
- # Mariana MCP
- Query the **[Mariana](https://mariana.santanabigdata.com.br)** graph database from Claude Code (and any MCP client): ask in plain language, and Claude reads the schema, writes Cypher, runs it and explains the result.
- *Leia em português: [README.pt-BR.md](README.pt-BR.md).*
- - **Remote server, nothing to run locally:** `https://mariana.santanabigdata.com.br/mcp` (MCP streamable HTTP).
- - **Read-only.** No tool writes to the database.
- - **Free accounts:** query the public graph (`global`) with a daily query quota and a row limit per query. Personal data (CPF, CNPJ, names, contacts, addresses, amounts, dates) comes **masked** — you can search for an exact CPF or CNPJ, but the result is always masked. Full data is available on paid plans.
- ## 1. Get a token
- 1. [Create a free account](https://mariana.santanabigdata.com.br/signup) and confirm your email (or sign in if you have one).
- 2. Open **API tokens** in the user menu ([direct link](https://mariana.santanabigdata.com.br/tokens)) and create a token, e.g. "Claude Code on my laptop".
- 3. Copy it (`mrnk_…`). It is shown only once and is valid until you revoke it. Treat it like a password.
- ## 2. Install in the Claude Code extension for VS Code
- 1. Open the Claude Code panel in VS Code (the spark icon, or **Claude Code: Open** in the command palette).
- 2. Type **`/plugins`** in the prompt box and press Enter. The **Manage plugins** window opens.
- 3. **Marketplaces** tab: type `Santana-BigData/mariana-mcp` and add it.
- 4. **Plugins** tab: search for **mariana**, click **Install** and choose **Install for you**.
- 5. A form asks for the plugin settings: paste your **Mariana API token** (`mrnk_…`). It is stored in your system's secure storage. Skipped it? Open the plugin's row and click the gear icon (or **Configure**).
- 6. Start a new conversation and type **`/mcp`**: `plugin:mariana:mariana` must show **Connected** (**Failed** means a wrong or revoked token). If the window says **Restart Claude to apply plugin changes**, do it.
- > In the VS Code panel, typing `/plugin marketplace add …` or `/plugin install …` in the prompt box does **not** work ("isn't available in this environment"). Use the `/plugins` window above, or the terminal commands below.
- Prefer the terminal? In VS Code's integrated terminal (needs the `claude` CLI installed; the extension doesn't add it to the PATH):
- ```bash
- claude plugin marketplace add Santana-BigData/mariana-mcp
- claude plugin install mariana@mariana-mcp
- ```
- The extension and the CLI share the same settings, so a plugin installed in one shows up in the other. Then open `/plugins` → **Plugins** → mariana → gear icon to set the token, and start a new conversation.
- ## 2b. Install in Claude Code in the terminal (CLI)
- Inside Claude Code:
- ```text
- /plugin marketplace add Santana-BigData/mariana-mcp
- /plugin install mariana@mariana-mcp
- ```
- (or the full URL: `https://github.com/Santana-BigData/mariana-mcp.git`). Needs a recent Claude Code (the token prompt uses plugin user settings): run `claude update` if `/plugin install` complains about `userConfig`. Claude Code asks for your **Mariana API token** when the plugin is enabled and keeps it in secure storage. Then run `/mcp`: `plugin:mariana:mariana` should show **connected**.
- The plugin brings:
- - the `mariana` MCP server (tools below);
- - the `/mariana:query` skill, which teaches Claude how to query Mariana well (schema first, selective entry points, parameters, limits, quota). Claude also uses it on its own when you ask about Mariana data.
- Update with `/plugin marketplace update mariana-mcp`; remove with `/plugin uninstall mariana@mariana-mcp` (and revoke the token).
- ### Without the plugin
- Plain MCP server, token from an environment variable:
- ```bash
- export MARIANA_TOKEN='mrnk_...'
- claude mcp add --transport http --scope user mariana \
- https://mariana.santanabigdata.com.br/mcp \
- --header "Authorization: Bearer $MARIANA_TOKEN"
- ```
- (or run [`clients/claude-code.sh`](clients/claude-code.sh)). For a team project, commit [`clients/project.mcp.json`](clients/project.mcp.json) as `.mcp.json`: the token stays out of git, each person exports `MARIANA_TOKEN`.
- ## 3. Use it
- - "What graphs can I query in Mariana, and what's in the `global` schema?"
- - "Find people named José Silva and show who they are connected to."
- - "Which partners of companies with tax debt also appear in lawsuits?"
- - "Show people who share the same phone number or address."
- - "Explain the plan for this query before running it: `MATCH (p:Pessoa)-[:SOCIO_DE]->(e:Empresa) RETURN e.razao_social, count(p) ORDER BY count(p) DESC LIMIT 10`"
- ## Tools
- | Tool | What it does | Uses quota |
- |---|---|---|
- | `list_graphs` | Graphs your account can query | no |
- | `get_schema` | Labels, properties (type, required, unique, searchable) and relationship types with their label pairs | no |
- | `query` | Runs read-only Cypher; returns columns, rows, cost, `truncated` and your `quota` | yes |
- | `explain` | Checks the query without running (admins also get the plan) | no |
- | `get_node` | A node's labels and properties by ID | no |
- | `neighbors` | A node, its neighbors and the edges between them | yes |
- | `whoami` | Your email, role and today's quota | no |
- Query errors (unknown label, syntax, quota reached, graph not allowed) come back as tool errors with the server's message, so Claude can fix the query and retry.
- ## Other clients
- | Client | Config |
- |---|---|
- | VS Code (Copilot agent mode) | [`clients/vscode.mcp.json`](clients/vscode.mcp.json) → `.vscode/mcp.json` (asks for the token) |
- | Cursor | [`clients/cursor.mcp.json`](clients/cursor.mcp.json) → `~/.cursor/mcp.json` (reads `MARIANA_TOKEN`) |
- | Claude Desktop | [`clients/claude-desktop.json`](clients/claude-desktop.json) → `claude_desktop_config.json` (via [`mcp-remote`](https://github.com/geelen/mcp-remote); needs Node 18+) |
- | Anything else | streamable HTTP at `https://mariana.santanabigdata.com.br/mcp` with `Authorization: Bearer <token>` |
- The MCP Registry entry is [`server.json`](server.json).
- ## Troubleshooting
- - **401 / "failed to connect":** wrong, revoked or missing token. Check it is listed as active on the API tokens page. With the env-var setups, `MARIANA_TOKEN` must exist in the shell that started the client.
- - **"your account can only query the graph …":** regular accounts query only `global`.
- - **"daily limit of N queries reached":** the quota resets at midnight (Brasília time).
- - Test by hand:
- ```bash
- curl -s https://mariana.santanabigdata.com.br/mcp \
- -H "Authorization: Bearer $MARIANA_TOKEN" -H 'content-type: application/json' \
- -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'
- ```
- ## Repository layout
- ```text
- .claude-plugin/marketplace.json Claude Code marketplace (this repo)
- plugins/mariana/.claude-plugin/plugin.json plugin: MCP server + token prompt
- plugins/mariana/skills/query/SKILL.md skill: how to query Mariana
- plugins/mariana/README.md, .claude-plugin/icon.png plugin listing
- server.json MCP Registry entry
- clients/ configs for other clients
- scripts/check.sh checks before a release
- ```
- ## Releasing
- 1. Bump `version` in `plugins/mariana/.claude-plugin/plugin.json` **and** `server.json` (same value, [SemVer](https://semver.org)); add a section to [`CHANGELOG.md`](CHANGELOG.md).
- 2. `./scripts/check.sh` (with `MARIANA_TOKEN` set, it also checks the live server).
- 3. Commit, tag and push: `git tag v0.2.0 && git push --follow-tags`.
- 4. Users get it with `/plugin marketplace update mariana-mcp`. To publish in the MCP Registry: `mcp-publisher validate && mcp-publisher publish` (the `br.com.santanabigdata/` namespace needs DNS authentication of the domain).
- ## License
- [MIT](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.