MCP Server
A custom Model Context Protocol (MCP) server that provides Claude Code and other MCP clients with secure access to filesystem, system information, Obsidian vault, SQLite database, and UniFi network controller tools.
Features
- Filesystem Tools - Read, write, list, and search files within allowed paths
- System Tools - Get system info, run whitelisted commands, view processes and disk usage
- Obsidian Tools - List notes, read content, search text, and find backlinks in your vault
- Database Tools - Query SQLite databases with read-only access
- UniFi Tools - Query and manage UniFi Dream Machine networks, including Threat Management (CyberSecure)
Security
- HTTPS with TLS certificates (Let's Encrypt supported)
- Bearer token authentication for all MCP requests
- Path restrictions for filesystem operations
- Command whitelist for system operations
- Read-only database access with query filtering
- API key authentication for UniFi integration
Requirements
- Node.js 18+ (for native fetch support)
- npm or yarn
- TLS certificates (self-signed for development, Let's Encrypt for production)
- Optional: UniFi Dream Machine with API key
Installation
-
Clone the repository:
git clone https://github.com/Shawn-Falconbury/mcp-server.git cd mcp-server -
Install dependencies:
npm install -
Configure environment:
cp .env.example .env # Edit .env with your settings -
Generate TLS certificates (for development):
mkdir -p certs openssl req -x509 -newkey rsa:4096 -keyout certs/server.key -out certs/server.crt -days 365 -nodes -subj "/CN=localhost" -
Build and run:
npm run build npm start
Configuration
Copy .env.example to .env and configure:
| Variable | Required | Description |
|---|---|---|
MCP_TOKEN | Yes | Authentication token for MCP clients |
MCP_PORT | No | Server port (default: 8443) |
USE_HTTPS | No | Use HTTPS (default: true) |
SSL_CERT_PATH | No | Path to SSL certificate |
SSL_KEY_PATH | No | Path to SSL private key |
ALLOWED_PATHS | No | Comma-separated paths for filesystem access |
OBSIDIAN_VAULT_PATH | No | Path to Obsidian vault |
DB_PATH | No | Path to SQLite database |
UNIFI_HOST | No | UniFi controller IP/hostname |
UNIFI_API_KEY | No | UniFi API key |
UNIFI_SITE | No | UniFi site name (default: "default") |
Usage
Development
npm run dev # Run with tsx (hot reload)
Production
npm run build # Compile TypeScript
npm start # Run compiled server
Systemd Service
Create /etc/systemd/system/mcp-server.service:
[Unit]
Description=MCP Server
After=network.target
[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/mcp-server
ExecStart=/usr/bin/npm start
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
Then:
sudo systemctl daemon-reload
sudo systemctl enable mcp-server
sudo systemctl start mcp-server
Connecting Claude Code
Add to your Claude Code MCP settings:
{
"mcpServers": {
"my-mcp-server": {
"type": "http",
"url": "https://your-server:8443/mcp",
"headers": {
"Authorization": "Bearer YOUR_MCP_TOKEN"
}
}
}
}
Available Tools
See docs/tools-reference.md for complete tool documentation.
Tool Categories
| Category | Tools | Description |
|---|---|---|
| Filesystem | 4 | File read/write/list/search |
| System | 4 | System info and commands |
| Obsidian | 4 | Vault notes and search |
| Database | 3 | SQLite queries |
| UniFi | 17 | Network management and security |
Project Structure
mcp-server/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # Express + MCP setup
│ ├── auth.ts # Token authentication
│ └── tools/
│ ├── index.ts # Tool registry
│ ├── filesystem.ts # File operations
│ ├── system.ts # System commands
│ ├── obsidian.ts # Obsidian vault
│ ├── database.ts # SQLite queries
│ └── unifi.ts # UniFi controller
├── docs/ # Documentation
├── certs/ # TLS certificates (not in repo)
├── dist/ # Compiled output (not in repo)
├── .env # Configuration (not in repo)
└── .env.example # Example configuration
API Endpoints
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/health | GET | No | Health check |
/mcp | POST | Yes | MCP protocol endpoint |
License
ISC
Contributing
Contributions are welcome! Please feel free to submit issues and pull requests.