Skip to content
Back to search

mariana-mcp

MarketplaceWorks with Claude CodeGitHub

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/santana-bigdata--mariana-mcp/badge.svg)](/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
  1. {
  2. "name": "mariana-mcp",
  3. "owner": {
  4. "name": "Santana Big Data",
  5. "url": "https://mariana.santanabigdata.com.br"
  6. },
  7. "metadata": {
  8. "description": "Mariana graph database for Claude Code: MCP server and query skill."
  9. },
  10. "plugins": [
  11. {
  12. "name": "mariana",
  13. "source": "./plugins/mariana",
  14. "description": "Query the Mariana graph database from Claude Code (read-only MCP server + Cypher skill).",
  15. "category": "database",
  16. "tags": ["mcp", "graph", "database", "cypher"]
  17. }
  18. ]
  19. }
README.md · README · 135 lines
  1. # Mariana MCP
  2. 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.
  3. *Leia em português: [README.pt-BR.md](README.pt-BR.md).*
  4. - **Remote server, nothing to run locally:** `https://mariana.santanabigdata.com.br/mcp` (MCP streamable HTTP).
  5. - **Read-only.** No tool writes to the database.
  6. - **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.
  7. ## 1. Get a token
  8. 1. [Create a free account](https://mariana.santanabigdata.com.br/signup) and confirm your email (or sign in if you have one).
  9. 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".
  10. 3. Copy it (`mrnk_…`). It is shown only once and is valid until you revoke it. Treat it like a password.
  11. ## 2. Install in the Claude Code extension for VS Code
  12. 1. Open the Claude Code panel in VS Code (the spark icon, or **Claude Code: Open** in the command palette).
  13. 2. Type **`/plugins`** in the prompt box and press Enter. The **Manage plugins** window opens.
  14. 3. **Marketplaces** tab: type `Santana-BigData/mariana-mcp` and add it.
  15. 4. **Plugins** tab: search for **mariana**, click **Install** and choose **Install for you**.
  16. 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**).
  17. 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.
  18. > 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.
  19. Prefer the terminal? In VS Code's integrated terminal (needs the `claude` CLI installed; the extension doesn't add it to the PATH):
  20. ```bash
  21. claude plugin marketplace add Santana-BigData/mariana-mcp
  22. claude plugin install mariana@mariana-mcp
  23. ```
  24. 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.
  25. ## 2b. Install in Claude Code in the terminal (CLI)
  26. Inside Claude Code:
  27. ```text
  28. /plugin marketplace add Santana-BigData/mariana-mcp
  29. /plugin install mariana@mariana-mcp
  30. ```
  31. (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**.
  32. The plugin brings:
  33. - the `mariana` MCP server (tools below);
  34. - 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.
  35. Update with `/plugin marketplace update mariana-mcp`; remove with `/plugin uninstall mariana@mariana-mcp` (and revoke the token).
  36. ### Without the plugin
  37. Plain MCP server, token from an environment variable:
  38. ```bash
  39. export MARIANA_TOKEN='mrnk_...'
  40. claude mcp add --transport http --scope user mariana \
  41. https://mariana.santanabigdata.com.br/mcp \
  42. --header "Authorization: Bearer $MARIANA_TOKEN"
  43. ```
  44. (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`.
  45. ## 3. Use it
  46. - "What graphs can I query in Mariana, and what's in the `global` schema?"
  47. - "Find people named José Silva and show who they are connected to."
  48. - "Which partners of companies with tax debt also appear in lawsuits?"
  49. - "Show people who share the same phone number or address."
  50. - "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`"
  51. ## Tools
  52. | Tool | What it does | Uses quota |
  53. |---|---|---|
  54. | `list_graphs` | Graphs your account can query | no |
  55. | `get_schema` | Labels, properties (type, required, unique, searchable) and relationship types with their label pairs | no |
  56. | `query` | Runs read-only Cypher; returns columns, rows, cost, `truncated` and your `quota` | yes |
  57. | `explain` | Checks the query without running (admins also get the plan) | no |
  58. | `get_node` | A node's labels and properties by ID | no |
  59. | `neighbors` | A node, its neighbors and the edges between them | yes |
  60. | `whoami` | Your email, role and today's quota | no |
  61. 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.
  62. ## Other clients
  63. | Client | Config |
  64. |---|---|
  65. | VS Code (Copilot agent mode) | [`clients/vscode.mcp.json`](clients/vscode.mcp.json) → `.vscode/mcp.json` (asks for the token) |
  66. | Cursor | [`clients/cursor.mcp.json`](clients/cursor.mcp.json) → `~/.cursor/mcp.json` (reads `MARIANA_TOKEN`) |
  67. | 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+) |
  68. | Anything else | streamable HTTP at `https://mariana.santanabigdata.com.br/mcp` with `Authorization: Bearer <token>` |
  69. The MCP Registry entry is [`server.json`](server.json).
  70. ## Troubleshooting
  71. - **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.
  72. - **"your account can only query the graph …":** regular accounts query only `global`.
  73. - **"daily limit of N queries reached":** the quota resets at midnight (Brasília time).
  74. - Test by hand:
  75. ```bash
  76. curl -s https://mariana.santanabigdata.com.br/mcp \
  77. -H "Authorization: Bearer $MARIANA_TOKEN" -H 'content-type: application/json' \
  78. -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'
  79. ```
  80. ## Repository layout
  81. ```text
  82. .claude-plugin/marketplace.json Claude Code marketplace (this repo)
  83. plugins/mariana/.claude-plugin/plugin.json plugin: MCP server + token prompt
  84. plugins/mariana/skills/query/SKILL.md skill: how to query Mariana
  85. plugins/mariana/README.md, .claude-plugin/icon.png plugin listing
  86. server.json MCP Registry entry
  87. clients/ configs for other clients
  88. scripts/check.sh checks before a release
  89. ```
  90. ## Releasing
  91. 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).
  92. 2. `./scripts/check.sh` (with `MARIANA_TOKEN` set, it also checks the live server).
  93. 3. Commit, tag and push: `git tag v0.2.0 && git push --follow-tags`.
  94. 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).
  95. ## License
  96. [MIT](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.