# MCP NEAR Wallet Server

A Model Context Protocol (MCP) server for NEAR Protocol wallet operations. This server enables Claude Desktop and other MCP clients to interact with NEAR blockchain accounts.

## Features

- **check_balance**: Get the NEAR balance of any account
- **account_info**: Get detailed account information (balance, storage, state)
- **view_access_keys**: View all access keys for an account
- **transaction_status**: Check transaction status by hash
- **send_near**: Broadcast signed transactions

## Installation

### Prerequisites

- Python 3.10 or higher
- pip or uv package manager

### Install from source

```bash
cd ~/projects/near-market/mcp-near-wallet
pip install -e .
```

Or with uv:

```bash
uv pip install -e .
```

## Configuration

Create a `config.json` file in your working directory:

```json
{
  "rpc_url": "https://rpc.mainnet.near.org"
}
```

For testnet:

```json
{
  "rpc_url": "https://rpc.testnet.near.org"
}
```

See `config.example.json` for reference.

## Claude Desktop Setup

### macOS

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "near-wallet": {
      "command": "python",
      "args": [
        "-m",
        "mcp_near_wallet.server"
      ],
      "cwd": "~/projects/near-market/mcp-near-wallet"
    }
  }
}
```

### Windows

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "near-wallet": {
      "command": "python",
      "args": [
        "-m",
        "mcp_near_wallet.server"
      ],
      "cwd": "C:\\Users\\YourUser\\projects\\near-market\\mcp-near-wallet"
    }
  }
}
```

### Linux

Edit `~/.config/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "near-wallet": {
      "command": "python",
      "args": [
        "-m",
        "mcp_near_wallet.server"
      ],
      "cwd": "~/projects/near-market/mcp-near-wallet"
    }
  }
}
```

### Using uv (Recommended)

If you prefer using uv for dependency isolation:

```json
{
  "mcpServers": {
    "near-wallet": {
      "command": "uv",
      "args": [
        "--directory",
        "~/projects/near-market/mcp-near-wallet",
        "run",
        "mcp-near-wallet"
      ]
    }
  }
}
```

## Restart Claude Desktop

After updating the configuration, restart Claude Desktop completely:

1. Quit Claude Desktop
2. Restart the application
3. The NEAR Wallet tools should now be available

## Usage Examples

Once configured, you can ask Claude:

- "Check the balance of alice.near"
- "Show me account information for bob.near"
- "What access keys does charlie.near have?"
- "Check the status of transaction ABC123 sent by dave.near"

## Development

### Run tests

```bash
pytest
```

### Format code

```bash
black src/
ruff check src/
```

## Protocol

This server implements the Model Context Protocol (MCP) specification:

- **Transport**: JSON-RPC 2.0 over stdio
- **Tool Schema**: JSON Schema input validation
- **Response Format**: TextContent with JSON payloads

## NEAR RPC Endpoints

- **Mainnet**: https://rpc.mainnet.near.org
- **Testnet**: https://rpc.testnet.near.org

## Security Notes

⚠️ **Important**: This server is read-only by default. The `send_near` tool requires pre-signed transactions and does not handle private keys. Never share your NEAR private keys with any MCP server.

For transaction signing, use:
- NEAR CLI
- NEAR Wallet
- near-api-js
- Other official NEAR SDKs

## License

MIT

## Support

For issues and questions:
- NEAR Protocol: https://near.org
- MCP Specification: https://spec.modelcontextprotocol.io