<div align="center">
  <img src="./docs/images/Solana.jpeg" alt="Solana Logo" width="200"/>
</div>

<br/>

Model Context Protocol (MCP) server that enables AI agents like Claude to interact with the Solana blockchain network.

[![smithery badge](https://smithery.ai/badge/@fozagtx/solanaaiterminal)](https://smithery.ai/server/@fozagtx/solanaaiterminal)

## Features

- Official Solana documentation search
- Blockchain queries (accounts, transactions, blocks)
- Wallet management and creation
- Cryptographic signing operations
- Support for Devnet and Testnet

---

## Quick Start

### Prerequisites

- Node.js 18+
- pnpm 10.14.0+

### Installation

#### Installing via Smithery

To install Solana Dev Essentials automatically via [Smithery](https://smithery.ai/server/@fozagtx/solanaaiterminal):

```bash
npx -y @smithery/cli install @fozagtx/solanaaiterminal
```

#### Manual Installation
```bash
# Install dependencies
pnpm install

# Build the project
pnpm build
```

---

## Usage

### Development Mode

```bash
# Run in development mode
pnpm dev
```

### Production Mode

```bash
# Build the project
pnpm build

# Start the server
pnpm start
```

### Testing

```bash
pnpm test
```

### Clean Build

```bash
# Remove build artifacts
pnpm clean
```

---

## Configuration

### Environment Variables

Create a `.env` file in the root directory:

```bash
# Network Configuration
ENVIRONMENT=DEVNET              # DEVNET or TESTNET

# Wallet Configuration (required for signing)
AGENT_SECRET_KEY=your_base58_private_key_here

# Server Configuration
USE_STREAMABLE_HTTP=false       # true for HTTP mode
PORT=3000                       # HTTP server port
HOST=127.0.0.1                  # HTTP server host
```

See `.env.example` for a template.

---

## Network Information

### Devnet

- **Network:** Devnet
- **RPC URL:** https://api.devnet.solana.com
- **Explorer:** https://explorer.solana.com/?cluster=devnet
- **Native Token:** SOL (Devnet)
- **Faucet:** https://faucet.solana.com/

### Testnet

- **Network:** Testnet
- **RPC URL:** https://api.testnet.solana.com
- **Explorer:** https://explorer.solana.com/?cluster=testnet
- **Native Token:** SOL (Testnet)
- **Faucet:** https://faucet.solana.com/

---

## Project Structure

```
solana/
├── src/                  # Server source code
├── dist/                 # Built output
├── .env                  # Environment variables (gitignored)
├── .env.example          # Environment template
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── Dockerfile            # Docker configuration
├── .dockerignore         # Docker ignore patterns
├── smithery.yaml         # Smithery configuration
├── somnia-mcp-stdio.example.json           # STDIO mode config
├── somnia-mcp-streamable-http.json         # HTTP mode config
└── README.md             # This file
```

---

## Docker Support

Build and run with Docker:

```bash
# Build Docker image
docker build -t solana-mcp-server .

# Run container
docker run -p 3000:3000 --env-file .env solana-mcp-server
```

---

## Deployment

### MCP Server

For deployment instructions to Smithery or other platforms, see **[DEPLOYMENT.md](./DEPLOYMENT.md)**.

**Important:** Ensure `AGENT_SECRET_KEY` is set as an environment variable in your deployment platform, not hardcoded in the Dockerfile.

### Documentation Site

The `docs/` folder contains a static HTML documentation site. For hosting instructions, see **[docs/HOSTING.md](./docs/HOSTING.md)**.

**Quick Deploy:**

- GitHub Pages (recommended)
- Vercel: `vercel --prod`
- Netlify: Drag & drop at https://app.netlify.com/drop
- Surge: `cd docs && surge`

---

## Resources

- [Solana Documentation](https://docs.solana.com/)
- [Solana Explorer (Devnet)](https://explorer.solana.com/?cluster=devnet)
- [Solana Explorer (Testnet)](https://explorer.solana.com/?cluster=testnet)
- [Solana Discord](https://discord.gg/solana)
- [Solana Twitter](https://twitter.com/solana)
- [Model Context Protocol](https://modelcontextprotocol.io/)

---

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## License

MIT License

---

## Security Considerations

**Important Security Notes:**

1. **Private Keys:** Never commit your `AGENT_SECRET_KEY` to version control
2. **Environment Variables:** Use secure secret management for production
3. **API Access:** Limit MCP server access to trusted AI agents
4. **Testnet First:** Always test on Solana Devnet/Testnet before mainnet operations

---

## Troubleshooting

### Build Errors

```bash
# Clear all dependencies and rebuild
pnpm clean
rm -rf node_modules pnpm-lock.yaml
pnpm install
pnpm build
```

### Connection Issues

- Verify RPC URLs are accessible
- Check network environment (DEVNET vs TESTNET)
- Ensure correct network configuration

### Signing Failures

- Verify `AGENT_SECRET_KEY` is correctly formatted (base58)
- Check private key has required permissions
- Ensure sufficient balance for transaction fees

---

<div align="center">
  <p>Made with ❤️ for the Solana ecosystem</p>
</div>