Society Abstract MCP
FastMCP TypeScript server providing comprehensive wallet, token and smart contract utilities for Abstract Testnet/Mainnet
🛠️ Available Tools
1. ab_get_balance - Balance Checker
Get native ETH or ERC-20 token balance for any address with ENS support.
Parameters:
address(required): Wallet address or ENS name to check balance fortokenAddress(optional): ERC-20 contract address for token balancetokenSymbol(optional): Token symbol (e.g., "USDC") for well-known tokens
Example Usage:
// Get native ETH balance
{ address: "0x1234...abcd" }
// Get ERC-20 balance by contract
{ address: "vitalik.eth", tokenAddress: "0xA0b86a33E6F..." }
// Get balance by token symbol
{ address: "0x1234...abcd", tokenSymbol: "USDC" }
Returns: Human-readable balance as string (e.g., "1.234567")
2. ab_transfer_token - Token Transfer
Transfer native ETH or ERC-20 tokens to another address with ENS support.
Parameters:
to(required): Recipient address or ENS nameamount(required): Amount to transfer in human-readable formattokenAddress(optional): ERC-20 contract address for token transferstokenSymbol(optional): Token symbol for well-known tokens
Example Usage:
// Transfer native ETH
{ to: "0x1234...abcd", amount: "0.1" }
// Transfer ERC-20 by contract
{ to: "vitalik.eth", amount: "100", tokenAddress: "0xA0b86a33E6F..." }
// Transfer by token symbol
{ to: "0x1234...abcd", amount: "50", tokenSymbol: "USDC" }
Returns: Transaction hash of the successful transfer
3. ab_deploy_token_erc20 - ERC-20 Token Deployment
Deploy a new ERC-20 BasicToken contract to Abstract network.
Parameters:
name(required): Token name (e.g., "DemoToken")symbol(required): Token symbol/ticker (e.g., "DMT")initialSupply(required): Total supply in wei (18 decimals) as string
Example Usage:
// Deploy 1000 tokens (1000 * 10^18 wei)
{
name: "MyToken",
symbol: "MTK",
initialSupply: "1000000000000000000000"
}
Returns: Deployed contract address and deployment details
4. ab_agw_create_wallet - Abstract Global Wallet Creation
Deploy a new Abstract Global Wallet (smart contract account) for a given signer.
Parameters:
signer(optional): EOA signer address or ENS name. If omitted, uses server wallet as initial signer
Example Usage:
// Create AGW with specific signer
{ signer: "0x1234...abcd" }
// Create AGW with server wallet as signer
{ }
Returns: Smart account address and deployment transaction hash
5. ab_generate_wallet - EOA Wallet Generation
Generate a brand-new Externally Owned Account (EOA) with private key and address.
Parameters:
random_string(required): Any string for entropy (can be anything)
Example Usage:
{ random_string: "my-random-seed" }
Returns:
privateKey: 0x-prefixed 32-byte hex stringaddress: Checksummed Ethereum/Abstract address
⚠️ Security Note: Store the private key securely and never log it.
🚀 Quick Start
For MCP Client Integration
Using NPX (Recommended)
{
"mcpServers": {
"society-abstract-mcp": {
"command": "npx",
"args": ["-y", "society-abstract-mcp@0.1.4"],
"env": {
"ABSTRACT_PRIVATE_KEY": "your-private-key-here",
"ABSTRACT_RPC_URL": "https://api.testnet.abs.xyz",
"TESTNET": "true",
"PORT": "3101",
"MCP_DISABLE_PINGS": "true"
}
}
}
}
Using Local Build
{
"mcpServers": {
"society-abstract-mcp-local": {
"command": "node",
"args": ["/path/to/your/society_abstract_mcp/dist/server.js"],
"env": {
"ABSTRACT_PRIVATE_KEY": "your-private-key-here",
"ABSTRACT_RPC_URL": "https://api.testnet.abs.xyz",
"TESTNET": "true",
"PORT": "3101",
"MCP_DISABLE_PINGS": "true"
}
}
}
}
For Development
# 1. Install dependencies
npm install
# 2. Build the project
npm run build
# 3. Run development server
npm run dev
# 4. Run tests
npm run test
# 5. Run integration tests (requires funds)
INTEGRATION=1 npm run test:int
📋 Environment Variables
Required for MCP Client:
ABSTRACT_PRIVATE_KEY: EOA private key that pays gas feesABSTRACT_RPC_URL: Abstract network RPC URLTESTNET: "true" for testnet, "false" for mainnet
Optional for MCP Client:
PORT: HTTP port for the MCP server (default: 3101)MCP_DISABLE_PINGS: "true" to disable ping messages
Note: No .env file needed for production. All variables should be passed by the MCP client.
🏗️ Build & Deploy
# Build for production
npm run build
# Start production server
npm start
# Build outputs to dist/ with:
# - ESM modules
# - TypeScript definitions
# - Copied JavaScript assets
🧪 Testing
- Unit Tests:
npm run test(mocked, no gas required) - Integration Tests:
INTEGRATION=1 npm run test:int(requires testnet funds) - Balance Checker:
npm run balance(multi-network balance tool)
📖 Technical Details
- Framework: FastMCP with TypeScript
- Networks: Abstract Testnet/Mainnet
- Standards: ERC-20 tokens, Abstract Global Wallets
- Dependencies: viem, zksync-ethers, @abstract-foundation/agw-client
- Build Target: ES2022 (Node.js ≥ 16.14)
🤝 Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🆘 Support
- Issues: GitHub Issues
- Documentation: This README and inline code documentation
- Community: Join our Telegram