mcp

<div align="center">

<img src="assets/banner.svg" alt="Finch MCP" width="100%"/>

# Finch MCP

[![npm version](https://img.shields.io/npm/v/@finchagentic/mcp?color=000000&label=npm&logo=npm)](https://www.npmjs.com/package/@finchagentic/mcp)
[![Official MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.finchagentic%2Fmcp-000000)](https://registry.modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/license-MIT-000000.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A518-000000?logo=node.js&logoColor=white)](package.json)
[![Tools: 116](https://img.shields.io/badge/tools-116-000000)](#what-you-get)

**The runtime layer for Agentic AI.**

Persistent memory, autonomous agents, and workflows that survive every session.

[App](https://app.finchagentic.com) · [Docs](https://docs.finch.com) · [npm](https://www.npmjs.com/package/@finchagentic/mcp) · [X](https://x.com/finchagentic)

</div>

---

Most AI assistants disappear when the conversation ends. **Finch** gives them lasting state — memory that accumulates, agents that keep running, vaults that version knowledge, and workflows that continue after you close the chat.

## Why Finch

| | Without Finch | With Finch |
|--|---------------|------------|
| **Memory** | Resets every session | Full-text searchable + versioned vault, decays stale notes |
| **Agents** | One-shot tool calls | Named agents with state and audit history |
| **Workflows** | Manual chaining | Automations, monitors, packets, deep research |
| **Local** | Cloud-only | Vault + memory can run fully on your machine |

## Install

Always pin the version. Never use `@latest`.

```bash
# One-command installer (detects common MCP clients)
npx -y -p @finchagentic/mcp@4.6.2 finch install
```

### Claude Code

```bash
claude mcp add finch -s user -- npx -y -p @finchagentic/mcp@4.6.2 finch-mcp
```

### Cursor / Windsurf / Claude Desktop

```json
{
  "mcpServers": {
    "finch": {
      "command": "npx",
      "args": ["-y", "-p", "@finchagentic/mcp@4.6.2", "finch-mcp"]
    }
  }
}
```

### Hermes

```bash
hermes mcp add finch -- npx -y -p @finchagentic/mcp@4.6.2 finch-mcp
```

<details>
<summary>Config file paths</summary>

| Client | Path |
|--------|------|
| Claude Desktop (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor | `.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| VS Code | `.vscode/mcp.json` |
| Zed | `.config/zed/settings.json` |

</details>

No LLM API key required to start — 111 of 116 tools are plain reads/writes/on-chain calls your client's model already drives. Tools load on first use.

## Quick start

```bash
finch doctor          # health check
finch setup           # local vault / memory / providers
finch vault           # inspect local vault
finch orders          # schedule Robinhood Chain DCA / TP-SL order ticks
```

Try in your MCP client:

```
remember: I prefer conservative DeFi strategies, max 5% risk
spawn an agent called research-bot to track AI agent news, update it after each session
save this thesis to vault
```

## What you get

**116 tools** across four pillars:

| Pillar | What it does |
|--------|----------------|
| **Memory** | Full-text searchable memory + versioned vault + chronicle |
| **Agents** | Spawn, recall, update named agents — `agent_recall` also pulls related memory/vault context matching the agent's goal |
| **Workflows** | Automations, monitors, packets, deep research (auto-saves reports + auto-links related past research) |
| **Execution** | Base DeFi, Robinhood Chain, market data, web, GitHub |

`deep_research` auto-saves its report to vault and links related past reports; `code_session_save` does the same for coding sessions. `vault_save` and `agent_spawn` accept an optional `workspaceProject` matching the webapp's Projects.

Default palette is `core` (lighter context). Full set:

```json
"env": { "FINCH_TOOLS": "all" }
```

## Fully local

Finch is the runtime. **Your LLM is the brain. Your data stays yours.**

```bash
npx -y -p @finchagentic/mcp@4.6.2 finch setup
```

| Piece | Location |
|-------|----------|
| Vault | `~/.finch/vault/` |
| Wallet | `~/.finch/wallet.json` |
| Config | `~/.finch/config.json` |
| Brain | your MCP client's model |

## Registry

Finch is listed in the [official MCP Registry](https://registry.modelcontextprotocol.io):

```json
{ "name": "io.github.finchagentic/mcp", "version": "4.6.2" }
```

## Development

This repository ships the published npm distribution. See [CHANGELOG.md](CHANGELOG.md) for release history and [SECURITY.md](SECURITY.md) for the security model.

```bash
npm ci
npm run smoke        # verify package integrity + CLI entrypoints
```

## Support

- Issues: [github.com/finchagentic/mcp/issues](https://github.com/finchagentic/mcp/issues)
- Docs: [docs.finch.com](https://docs.finch.com)
- X: [@finchagentic](https://x.com/finchagentic)

<div align="center">

**Finch** — memory that survives every session.

</div>